Skip to content
Permalink

Comparing changes

This is a direct comparison between two commits made in this repository or its related repositories. View the default comparison for this range or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: jj-vcs/jj
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: ba772a0636c0730ccd412fd65a4a750f888e5df3
Choose a base ref
..
head repository: jj-vcs/jj
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: 1dc68e7e8d1b3ffb5074304f0faa6db8a16374dd
Choose a head ref
Showing with 16 additions and 14 deletions.
  1. +16 −14 docs/design/git-submodules.md
  2. 0 lib/src/submodule_store.rs
30 changes: 16 additions & 14 deletions docs/design/git-submodules.md
Original file line number Diff line number Diff line change
@@ -166,31 +166,33 @@ submodules _are_ standalone Git repositories:
We should keep in mind that a submodule exists to be integrated with a
superproject, otherwise, the submodule could just be an independent clone. As
such, jj should enforce tight integrations between superproject and submodule
tightly by requiring that all interactions with the submodule must be initiated
by requiring that all interactions with the submodule must be initiated
from the superproject.

#### Commands should involve submodules by default

Git does not recurse into submodules by default (it requires the
`--recurse-submodules` flag or the `submodule.recurse` config setting), and this
is a constant source of confusion for users, e.g.:
Submodules should be part of the 'regular' jj workflow. Users shouldn't have to
remember to tell jj to consider submodules and manual submodule management
should be reserved only for very exceptional cases. For example,

- Non-recursive `git clone` will not clone submodules, resulting in their
contents being unpopulated in the working tree.
- `jj git clone` should clone a 'reasonable' set of submodules.

- Non-recursive `git checkout` does not update the submodule index or working
tree, resulting in the submodule being 'dirty' and the working tree being out
of sync with the superproject.
- Updating the working copy in the superproject should also update the submodule
working copies.

We should always consider submodules. If they are ignored, we should be explicit
to the user.
Contrast these with Git, where the `--recurse-submodules` needs to be explicitly
passed, and is a constant source of confusion for users.

In exceptional cases, submodules might be excluded (e.g. a submodule remote
deletes the commits we rely on). We should anticipate these problems, recover
gracefully, and be explicit to the user.

#### Submodules are globally managed

In a regular jj or Git repository, objects are reusable because they are stored
in a central database, regardless of the working copy. Similarly, we should
manage submodules globally and treat that as the source of truth; the working
copy should, at best, be treated as a hint.
in a database independent of the working copy. Similarly, we should manage
submodules globally and treat that as the source of truth; the working copy
should, at best, be treated as a hint.

A consequence of this is that it is expected that the working copy may be out
of sync with the global submodules, e.g. submodules may be missing, their
Empty file added lib/src/submodule_store.rs
Empty file.