Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Clone this wiki locally
Welcome to the git-submod-enhancements wiki!
As Dscho put it, submodules are the “neglected ugly duckling” of git. Time to change that …
Here we collect ideas, design descriptions of certain parts of the submodule implementation. If you want to help out, this is a good place to search for low hanging fruits to get started. The topics described here vary in complexity. If you are unsure about the complexity feel free to ask on the mailing list.
The started but stalled issues are also a good place to dive in, since they already have some existing code modifications, which you can follow and use to familiarize yourself with submodule part of the code base.
Issues currently being worked on
- Add configuration options (global and per repo) to set the default of
git push --recurse-submodules
- Recursive submodule checkout: teach all work tree manipulating commands to update the submodule work trees according to the commit recorded in the superproject. (branch on github )
git fetchto also fetch commits for submodule not currently in the work tree into .git/modules/ (branch on github ).
- Submodule support for rev-parse by Phil Hord
Issues started but stalled
Stalled: Add recurse submodule functionality to
git archive(thread on mailinglist )
--recursiveoption (thread on mailinglist)
Issues still to be tackled
- Add functionality to move the .git directory of a submodule into the .git/modules directory of the superproject (either by adding a new
git submodulecommand or by providing a script in contrib/)
- Add a git-config aware merge driver and make it the default for .gitmodules
- Attempt a 3-way merge when
git submodule addwant to change a .gitmodules file which has unstaged changes
- Add configuration options (per submodule) to set the default of
git push --recurse-submodules
- Add a tutorial explaining the different use cases and the configuration settings which suit them.
- Add an option to
git submodule addto move the .git directory of a local repository to be added as submodule into the .git/modules directory of the superproject
- Add means to specify which submodules shall be populated on clone (which I’d like to implement by teaching
git fetchto create submodule repos in .git/modules, recursive checkout will then do the rest)
- Showing that a submodule has a HEAD not on any branch in the
git statusof the superproject
gitk: Add popup menu for submodules to see the detailed history of changes
--recurse-submodulesoption (and maybe honour the same default and options
- Better support for displaying merge conflicts of submodules
git gui: Add submodule menu for adding and fetching submodules
git statusshould call
git diff --submodule --ignore-submodules=dirtyinstead of
git submodule summaryfor providing a submodule summary when configured to do so.
- Other commands that could benefit from a
- To enable history rewriting
git filter-branchcould write a list of rewritten commits which can then be used to update submodule commits in a superproject.
- Much more documentation: E.g. update description in Documentation/user-manual.txt, Extend the pro-git book, Write blog posts, …
In the long run, git-submodule.sh should be converted to a rather simple wrapper script around core Git functionality, as more and more of that is implemented in the git core. For that we need extensive submodule update tests. Johan Herland has started a collection .
Submodule related bugs to fix
- Cherry picking across submodule creation fails even if the cherry pick doesn’t touch any file in the submodules path
git submodule adddoesn’t record the URL in .git/config when the submodule path doesn’t exist
git submodule addhappily stages any unstaged modifications of the .gitmodules file together with the new section while it should error out telling the user to stash them (at least unless it attempts the 3-way merge described in the “Issues still to be tackled” paragraph)
git log <submodule>/and
git diff <rev> <submodule>/do not produce any output while dropping the ‘/’ at the end makes them work as expected.
git adddoes not honour the submodule.<name>.ignore settings
git submodule addmesses up paths from nested submodules, see (thread on mailing list)
git commitcan be cautious about submodule related commits. That is if a commit contains a change to the .gitmodules file, make sure that the corresponding gitlink is present (either already in the tree or newly added). IIUC Jonathan correctly a submodule which is configured in .gitmodules, but not present as a gitlink is considered broken, which we may want to avoid in the first place. When implementing this, we need to take care of historical mistakes being handled correctly as well as a flag to commit, which overwrites the potential warning. The gitmodules file unlike other in-tree configuration files (.gitignore, .gitattributes, .mailmap) have a 1:1 mapping so the existence of the gitlink is strongly expected. (Counter example with .gitignore: Ignoring *.exe doesn’t expect any .exe file to be there). I imagine this to roughly work as:
$ git add .gitmodules $ git commit -m "add submodule to .gitmodules, but not as gitlink" Warning: Not committing as this would break submodule consistency. Use --force-submodules to commit the broken submodule state. $ echo $? 1 # fail $ git commit --force-submodules -m "add submodule to .gitmodules, but not as gitlink" $ echo $? 0 # Success