docs/design/git-submodules.md
This is an aspirational document that describes how jj will support Git submodules. Readers are assumed to have some familiarity with Git and Git submodules.
This document is a work in progress; submodules are a big feature, and relevant details will be filled in incrementally.
This proposal aims to replicate the workflows users are used to with Git submodules, e.g.:
When it is convenient, this proposal will also aim to make submodules easier to use than Git's implementation.
We mainly want to support Git submodules for feature parity, since Git submodules are a standard feature in Git and are popular enough that we have received user requests for them. Secondarily (and distantly so), Git submodules are notoriously difficult to use, so there is an opportunity to improve the UX over Git's implementation.
Git submodules are a feature of Git that allow a repository (submodule) to be embedded inside another repository (the superproject). Notably, a submodule is a full repository, complete with its own index, object store and ref store. It can be interacted with like any other repository, regardless of the superproject.
In a superproject commit, submodule information is captured in two places:
A gitlink entry in the commit's tree, where the value of the gitlink entry
is the submodule commit id. This tells Git what to populate in the working
tree.
A top level .gitmodules file. This file is in Git's config syntax and
entries take the form submodule.<submodule-name>.*. These include many
settings about the submodules, but most importantly:
submodule<submodule-name>.path contains the path from the root of the tree
to the gitlink being described.
submodule<submodule-name>.url contains the url to clone the submodule
from.
In the working tree, Git notices the presence of a submodule by the .git entry
(signifying the root of a Git repository working tree). This is either the
submodule's actual Git directory (an "old-form" submodule), or a .git file
pointing to <superproject-git-directory>/modules/<submodule-name>. The latter
is sometimes called the "absorbed form", and is Git's preferred mode of
operation.
Git submodules should be implemented in an order that supports an increasing set of workflows, with the goal of getting feedback early and often. When support is incomplete, jj should not crash, but instead provide fallback behavior and warn the user where needed.
The goal is to land good support for pure Jujutsu workspaces, while colocated workspaces will be supported when convenient.
This section should be treated as a set of guidelines, not a strict order of work.
This includes work that inspects submodule contents but does not create new objects in the submodule. This requires a way to store submodules in a jj repository that supports readonly operations.
This allows a user to write new contents to a submodule and its remote.
This allows merging and rebasing of superproject commits in a content-aware way (in contrast to Git, where only the gitlink commit ids are compared), as well as workflows that make resolving conflicts easy and sensible.
This can be done in tandem with Phase 2, but will likely require a significant amount of design work on its own.
I.e. outcomes we would like to see if there were no constraints whatsoever.
TODO
Possible approaches under discussion. See ./git-submodule-storage.md.
TODO
TODO