Skip to content

Home

Jump to bottom
Stefan Beller edited this page Mar 16, 2016 · 91 revisions

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

Issues started but stalled

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 submodule command 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 mv, git rm or git submodule add want 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 add to 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 fetch to 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 status of the superproject
  • gitk: Add popup menu for submodules to see the detailed history of changes
  • Teach git prune the --recurse-submodules option (and maybe honour the same default and options git fetch uses)
  • Better support for displaying merge conflicts of submodules
  • git gui: Add submodule menu for adding and fetching submodules
  • git status should call git diff --submodule --ignore-submodules=dirty instead of git submodule summary for providing a submodule summary when configured to do so.
  • Other commands that could benefit from a --recurse-submodules option: archive, branch, clean, commit, revert, tag.
  • To enable history rewriting git filter-branch could 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 add doesn’t record the URL in .git/config when the submodule path doesn’t exist
  • git submodule add happily 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)
  • E.g. 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 add does not honour the submodule.<name>.ignore settings
  • git submodule add messes up paths from nested submodules, see (thread on mailing list)
  • git commit can 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

Ideas

Issues already solved and merged into Junio's Repo

Clone this wiki locally