git-nested 1.2.0__py3-none-any.whl → 1.2.2__py3-none-any.whl

git_nested/checks.py

@@ -20,7 +20,7 @@ def check_repository(git: GitRunner, command: str, flags: Flags) -> tuple[Path |
         return None, None
 
     try:
-        git.run(['rev-parse', '--git-dir'])
+        git_dir, inside_work_tree = git.check_output(['rev-parse', '--git-dir', '--is-inside-work-tree']).splitlines()
     except GitNestedError:
         # A deliberate re-interpretation of git's own message, not an
         # incidental failure, so the chain is suppressed -- and since
@@ -29,14 +29,14 @@ def check_repository(git: GitRunner, command: str, flags: Flags) -> tuple[Path |
         raise GitNestedError("not inside a git repository") from None
 
     # Per worktree of this repository, so they do not block each other.
-    git_tmp = Path(git.check_output(['rev-parse', '--git-dir'])) / 'tmp'
+    git_tmp = Path(git_dir) / 'tmp'
 
     # Not a nested branch. A detached HEAD is fine: commits go there, as with git commit.
     current_branch = git.check_output(['symbolic-ref', '--short', '--quiet', 'HEAD'], may_fail=True)
     if current_branch.startswith('nested/'):
         raise GitNestedError(f"can't {command} while the nested branch {current_branch} is checked out")
 
-    if git.check_output(['rev-parse', '--is-inside-work-tree'], may_fail=True) != 'true':
+    if inside_work_tree != 'true':
         raise GitNestedError("not inside a git working tree")
 
     if _needs_clean_worktree(command, flags):
@@ -55,7 +55,18 @@ def _needs_clean_worktree(command: str, flags: Flags) -> bool:
 
 def check_worktree_clean(git: GitRunner, command: str) -> None:
     """Ensure working copy has no uncommitted changes."""
-    if command not in ['clone', 'init', 'pull', 'push', 'branch', 'commit', 'diff', 'repair']:
+    if command not in [
+        'clone',
+        'init',
+        'pull',
+        'push',
+        'branch',
+        'commit',
+        'diff',
+        'repair',
+        'drop a patch',
+        'cherry-pick a patch',
+    ]:
         return
 
     pwd = Path.cwd().as_posix()
@@ -74,13 +85,15 @@ def check_worktree_clean(git: GitRunner, command: str) -> None:
         raise GitNestedError(f"{pwd}: can't {command}, the index has changes")
 
 
-def warn_uncommitted_subdir_changes(git: GitRunner, command: str, flags: Flags, subdir: Path) -> None:
-    """Warn when `command` ignores uncommitted changes in `subdir`."""
-    if command not in ['branch', 'diff', 'push'] or (command == 'push' and flags.commit):
+def warn_uncommitted_subdir_changes(
+    git: GitRunner, command: str, flags: Flags, subdir: Path, skip: str | None = None
+) -> None:
+    """Warn when `command` ignores uncommitted changes in `subdir`, but not in `skip` inside it."""
+    if command not in ['branch', 'diff', 'patches', 'push', 'verify'] or (command == 'push' and flags.commit):
         return
 
     git.run(['update-index', '-q', '--ignore-submodules', '--refresh'], may_fail=True)
-    pathspec = ['--', subdir.as_posix()]
+    pathspec = ['--', subdir.as_posix(), *([f':(exclude,literal){subdir.as_posix()}/{skip}'] if skip else [])]
     if git.run(['diff-files', '--quiet', '--ignore-submodules', *pathspec], may_fail=True).returncode != 0:
         output.warn(f"{subdir.as_posix()}: has uncommitted changes; {command} uses only committed content")
         return

git_nested/cli/location.py

@@ -29,7 +29,7 @@ if TYPE_CHECKING:
 # Commands whose missing <subdir> is not filled in from the current directory:
 # status reports on all of them, clone guesses one from the upstream, and init
 # is what makes a directory nested in the first place.
-_NO_IMPLIED_SUBDIR = ('clone', 'completion', 'init', 'status', 'version')
+_NO_IMPLIED_SUBDIR = ('clone', 'completion', 'init', 'status', 'submodules', 'version')
 
 
 def at_top_level(git: GitRunner, command: str, ctx: CommandContext) -> AbstractContextManager[object]:
@@ -49,14 +49,20 @@ def at_top_level(git: GitRunner, command: str, ctx: CommandContext) -> AbstractC
     # Path options are made absolute, so moving to the top level does not change what they name.
     ctx.flags.dir = _absolute(ctx.flags.dir)
     ctx.flags.message_file = _absolute(ctx.flags.message_file)
+    ctx.flags.output_dir = _absolute(ctx.flags.output_dir)
+    ctx.patches = _all_absolute(ctx.patches)
     # Remotes given as relative paths are rebased onto the top level instead.
     # Relative rather than absolute: a remote ends up in .gitnested, and a
     # relative one keeps working in every clone of the parent repository.
     ctx.upstream = _remote_from(prefix, ctx.upstream)
     ctx.flags.remote = _remote_from(prefix, ctx.flags.remote)
+    ctx.flags.resolve_relative = _remote_from(prefix, ctx.flags.resolve_relative)
     if ctx.config_key == 'remote':
         ctx.config_value = _remote_from(prefix, ctx.config_value)
 
+    # --ignore and --only paths are given like <subdir>.
+    ctx.flags.ignore = _all_joined(prefix, ctx.flags.ignore)
+    ctx.flags.only = _all_joined(prefix, ctx.flags.only)
     if ctx.subdir is not None:
         ctx.subdir = _joined(prefix, Path(ctx.subdir))
     elif command not in _NO_IMPLIED_SUBDIR and not ctx.flags.all:
@@ -73,6 +79,11 @@ def _absolute(path: str | None) -> str | None:
     return os.path.abspath(path) if path else None  # noqa: PTH100
 
 
+def _all_absolute(paths: list[str] | None) -> list[str] | None:
+    """Each of `paths` made absolute."""
+    return [os.path.abspath(path) for path in paths] if paths else paths  # noqa: PTH100
+
+
 def _remote_from(prefix: str, remote: str | None) -> str | None:
     """`remote`, typed below the top level at `prefix`, as seen from the top level.
 
@@ -90,6 +101,11 @@ def _remote_from(prefix: str, remote: str | None) -> str | None:
     return joined if joined.startswith('.') else f'./{joined}'
 
 
+def _all_joined(prefix: str, paths: list[str] | None) -> list[str] | None:
+    """Each of `paths` joined like a <subdir>. None stays None."""
+    return [_joined(prefix, Path(path)) for path in paths] if paths else paths
+
+
 def _joined(prefix: str, subdir: Path) -> str:
     """`subdir`, typed below the top level at `prefix`, as a path from the top level."""
     if subdir.anchor:

git_nested/cli/parser.py

@@ -69,7 +69,13 @@ def _flags_from_args(args: argparse.Namespace) -> Flags:
         dry_run=getattr(args, 'dry_run', False),
         filter=getattr(args, 'filter', []),
         force=getattr(args, 'force', False),
+        ignore=getattr(args, 'ignore', None),
+        only=getattr(args, 'only', None),
+        resolve_relative=getattr(args, 'resolve_relative', None),
+        recursive=getattr(args, 'recursive', False),
         from_submodule=getattr(args, 'from_submodule', False),
+        from_patches=getattr(args, 'from_patches', False),
+        local=getattr(args, 'local', False),
         recurse_submodules=getattr(args, 'recurse_submodules', False),
         gpg_sign=getattr(args, 'gpg_sign', False),
         signoff=getattr(args, 'signoff', False),
@@ -79,6 +85,9 @@ def _flags_from_args(args: argparse.Namespace) -> Flags:
         no_squash=getattr(args, 'no_squash', False),
         squash=getattr(args, 'squash', False),
         update=getattr(args, 'update', False),
+        keep=getattr(args, 'keep', False),
+        resume=getattr(args, 'resume', False),
+        abort=getattr(args, 'abort', False),
         quiet=getattr(args, 'quiet', False),
         # argparse's `count` action leaves the attribute at None when the flag
         # is absent, and the output layer wants a real count.
@@ -102,6 +111,7 @@ _EXCLUSIVE_FLAGS = (
     ('all', 'dir', "--dir names one worktree, so it can't be used with --all"),
     ('all', 'name', "--name names one branch, so it can't be used with --all"),
     ('dry_run', 'commit', "--dry-run can't be combined with --commit"),
+    ('from_patches', 'gpg_sign', "--from-patches can't sign the commits, so it can't be used with -S"),
 )
 
 
@@ -114,6 +124,56 @@ def _check_flags(flags: Flags) -> None:
         output.usage_error("--update needs --branch or --remote to have something to update")
 
 
+def _verify_files(args: argparse.Namespace) -> tuple[list[str] | None, str]:
+    """The files of --patches or --diffs, and which of the two it is."""
+    patches, diffs = getattr(args, 'patches', None), getattr(args, 'diffs', None)
+    if patches is not None and diffs is not None:
+        output.usage_error("--patches and --diffs can't be used together")
+    if diffs is not None:
+        return diffs, 'diff'
+    return patches, 'patches'
+
+
+def _options_last(args_list: list[str], command: str) -> list[str]:
+    """For `command`, its options after its positionals: `patches cherry-pick -r X bar c` as `... bar c -r X`.
+
+    Before Python 3.12, argparse can't take a positional after an option
+    once an earlier positional is parsed. Moving the options to the end
+    keeps each option with its value.
+    """
+    start = next((index for index, arg in enumerate(args_list) if not arg.startswith('-')), None)
+    if start is None or args_list[start] != command:
+        return args_list
+    positionals, options = _split_options(args_list[start + 1 :], _taking_a_value(command))
+    return [*args_list[: start + 1], *positionals, *options]
+
+
+def _taking_a_value(command: str) -> set[str]:
+    """The option names of `command` that take a value."""
+    return {
+        name
+        for opt, names, kwargs in SUBPARSER_ARG_SPECS
+        if opt in VALID_COMMAND_OPTIONS[command] and kwargs.get('action') not in ('store_true', 'store_const')
+        for name in names
+    }
+
+
+def _split_options(args: list[str], takes_value: set[str]) -> tuple[list[str], list[str]]:
+    """`args` as positionals and options, each option with its value."""
+    positionals: list[str] = []
+    options: list[str] = []
+    rest = iter(args)
+    for arg in rest:
+        if not arg.startswith('-'):
+            positionals.append(arg)
+            continue
+        options.append(arg)
+        value = next(rest, None) if arg in takes_value else None
+        if value is not None:
+            options.append(value)
+    return positionals, options
+
+
 def parse_args(git: GitRunner, args_list: list[str]) -> tuple[str, CommandContext]:
     """Parse command line arguments into a command name and the context to run it with.
 
@@ -121,7 +181,7 @@ def parse_args(git: GitRunner, args_list: list[str]) -> tuple[str, CommandContex
         tuple: (command, context). The context's git_tmp/head_commit are left
         unset -- only the caller knows whether the command runs in a repository.
     """
-    args = build_arg_parser().parse_args(args_list)
+    args = build_arg_parser().parse_args(_options_last(_options_last(args_list, 'patches'), 'submodules'))
 
     if args.version:
         args.command = 'version'
@@ -130,9 +190,10 @@ def parse_args(git: GitRunner, args_list: list[str]) -> tuple[str, CommandContex
 
     flags = _flags_from_args(args)
     _check_flags(flags)
-    if flags.single_commit and not flags.all:
+    if flags.single_commit and not flags.all and args.command != 'submodules':
         output.usage_error("--single-commit needs --all")
 
+    patches, verify_mode = _verify_files(args)
     upstream = getattr(args, 'upstream', None)
     subdir = getattr(args, 'subdir', None)
     if upstream and not subdir:
@@ -150,5 +211,11 @@ def parse_args(git: GitRunner, args_list: list[str]) -> tuple[str, CommandContex
         config_key=getattr(args, 'key', None),
         config_value=getattr(args, 'value', None),
         git_args=getattr(args, 'git_args', None),
+        patches_action=getattr(args, 'action', None),
+        patch_names=getattr(args, 'patch_names', None),
+        patches=patches,
+        verify_mode=verify_mode,
+        submodules_action=getattr(args, 'submodules_action', None),
+        submodules_args=getattr(args, 'submodules_args', None),
     )
     return args.command, context

git_nested/cli/setup.py

@@ -48,7 +48,7 @@ def _check_existing_worktree(git: GitRunner, command: str, subdir: Path, gitnest
         output.error(
             f"{subdir.as_posix()}: no worktree to commit from; run 'git nested branch {subdir.as_posix()}' first"
         )
-    elif command not in ['branch', 'clean', 'commit', 'push', 'run'] and worktree_path is not None:
+    elif command not in ['branch', 'clean', 'commit', 'patches', 'push', 'run', 'verify'] and worktree_path is not None:
         output.error(messages.worktree_exists(subdir, worktree_path, prunable=gitnested.exists()))
 
 
@@ -61,7 +61,7 @@ def setup_command(
         tuple: (subdir, gitnested, subref, config)
     """
     subdir = resolve_subdir(subdir)
-    subref = refs.sanitize_subref(git, subdir.as_posix())
+    subref = refs.sanitize_subref(subdir.as_posix())
     gitnested = resolve_gitnested_file(subdir)
 
     if not flags.force:
@@ -69,9 +69,14 @@ def setup_command(
 
     # clone and init have no .gitnested yet. clean does not need it.
     if command in ['clone', 'init', 'clean']:
+        # Check nested.format now, not after the content is in place.
+        if command != 'clean':
+            gitfile.new_file_is_toml(git)
         config = NestedConfig(remote=flags.remote or upstream or '', branch=flags.branch or '', pin=flags.pin or '')
     else:
         config = gitfile.read_config(gitnested, flags)
 
-    checks.warn_uncommitted_subdir_changes(git, command, flags, subdir)
+    # `patches` reads the patches folder as it is, committed or not
+    skip = config.patches_inside(subdir) if command == 'patches' else None
+    checks.warn_uncommitted_subdir_changes(git, command, flags, subdir, skip)
     return subdir, gitnested, subref, config

git_nested/cli/spec.py

@@ -13,7 +13,7 @@ from ..constants import COMPLETION_SHELLS
 # Which flags each command accepts. The keys are also the command list:
 # the subparsers, and the completion candidates, are built from them.
 VALID_COMMAND_OPTIONS: dict[str, list[str]] = {
-    'branch': ['all', 'dir', 'fetch', 'force', 'gpg_sign', 'name'],
+    'branch': ['all', 'dir', 'fetch', 'force', 'from_patches', 'gpg_sign', 'name'],
     'clean': ['ALL', 'all', 'force'],
     'clone': [
         'adopt',
@@ -31,17 +31,19 @@ VALID_COMMAND_OPTIONS: dict[str, list[str]] = {
         'recurse_submodules',
         'signoff',
     ],
-    'commit': ['fetch', 'force', 'gpg_sign', 'message', 'msg_file', 'signoff'],
+    'commit': ['fetch', 'force', 'gpg_sign', 'message', 'msg_file', 'pin', 'signoff'],
     'completion': [],
     'config': [],
     'diff': ['all', 'branch', 'remote'],
     'fetch': ['all', 'branch', 'force', 'remote'],
     'init': ['branch', 'from_submodule', 'gpg_sign', 'remote', 'method', 'signoff', 'upstream_commit'],
+    'patches': ['all', 'local', 'remote'],
     'pull': [
         'all',
         'branch',
         'force',
         'gpg_sign',
+        'ignore',
         'merge',
         'message',
         'method',
@@ -63,6 +65,7 @@ VALID_COMMAND_OPTIONS: dict[str, list[str]] = {
         'dry_run',
         'force',
         'gpg_sign',
+        'ignore',
         'merge',
         'message',
         'method',
@@ -76,6 +79,19 @@ VALID_COMMAND_OPTIONS: dict[str, list[str]] = {
         'update',
     ],
     'status': ['ALL', 'all', 'fetch', 'short'],
+    'submodules': [
+        'abort',
+        'dry_run',
+        'gpg_sign',
+        'ignore',
+        'only',
+        'recursive',
+        'resolve_relative',
+        'resume',
+        'signoff',
+        'single_commit',
+    ],
+    'verify': ['diffs', 'ignore', 'keep', 'output_dir', 'patches'],
     'version': [],
 }
 
@@ -91,11 +107,14 @@ COMMAND_HELP: dict[str, str] = {
     'diff': "show a nested repository's local changes against upstream",
     'fetch': "fetch upstream content for a nested repository",
     'init': "turn an existing subdirectory into a nested repository",
+    'patches': "write, check, drop or cherry-pick the patches of a nested repository",
     'pull': "update a nested repository from its upstream",
     'push': "push a nested repository's local changes upstream",
     'repair': "point a nested repository's sync point back into the current history",
     'run': "run a git command in the worktree of a nested repository",
     'status': "report on the nested repositories of this repository",
+    'submodules': "turn all submodules into nested repositories and keep them up to date",
+    'verify': "check that a nested repository is its upstream commit plus patches or diffs",
     'version': "print version information",
 }
 
@@ -135,18 +154,70 @@ SUBPARSER_ARG_SPECS: list[tuple[str, tuple[str, ...], dict]] = [
         ('-c', '--commit'),
         {'action': 'store_true', 'help': "record the pushed commit in .gitnested; needs a push to the tracked branch"},
     ),
-    ('dry_run', ('--dry-run',), {'action': 'store_true', 'dest': 'dry_run', 'help': "show what would be pushed"}),
+    (
+        'dry_run',
+        ('--dry-run',),
+        {'action': 'store_true', 'dest': 'dry_run', 'help': "show what would happen; change nothing"},
+    ),
+    (
+        'diffs',
+        ('--diffs',),
+        {'nargs': '*', 'metavar': 'DIFF', 'help': "check against these diffs, in order"},
+    ),
+    (
+        'keep',
+        ('-k', '--keep'),
+        {'action': 'store_true', 'help': "keep the temporary worktree"},
+    ),
     ('force', ('-f', '--force'), {'action': 'store_true', 'help': "force the operation"}),
     (
         'from_submodule',
         ('--from-submodule',),
         {'action': 'store_true', 'help': "turn the submodule at <subdir> into a nested repository"},
     ),
+    (
+        'local',
+        ('--local',),
+        {'action': 'store_true', 'help': "cherry-pick: add the new patches to patches-local"},
+    ),
+    (
+        'from_patches',
+        ('--from-patches',),
+        {'action': 'store_true', 'help': "build the branch from upstream and the patches; check it gives <subdir>"},
+    ),
     (
         'recurse_submodules',
         ('--recurse-submodules',),
         {'action': 'store_true', 'help': "nest the submodules of upstream too, at the commits it pins"},
     ),
+    (
+        'ignore',
+        ('--ignore',),
+        {
+            'action': 'append',
+            'metavar': 'PATH',
+            'help': "skip this path of <subdir>, just this time; submodules init: do not nest the submodules there",
+        },
+    ),
+    (
+        'only',
+        ('--only',),
+        {
+            'action': 'append',
+            'metavar': 'PATH',
+            'help': "init: nest only the submodules at or below this path; give it more than once for more",
+        },
+    ),
+    (
+        'recursive',
+        ('--recursive',),
+        {'action': 'store_true', 'help': "init: nest the submodules of the submodules too, at any depth"},
+    ),
+    (
+        'resolve_relative',
+        ('--resolve-relative',),
+        {'metavar': 'URL', 'help': "init: resolve relative submodule urls against this url"},
+    ),
     ('exclude', ('--exclude',), {'action': 'append', 'help': "leave this path of the upstream repository out"}),
     (
         'gpg_sign',
@@ -186,10 +257,33 @@ SUBPARSER_ARG_SPECS: list[tuple[str, tuple[str, ...], dict]] = [
         {'dest': 'name', 'help': "name of the nested branch; defaults to nested/<subdir>"},
     ),
     ('message', ('-m', '--message'), {'dest': 'message', 'help': "commit message"}),
+    (
+        'patches',
+        ('--patches',),
+        {'nargs': '*', 'metavar': 'PATCH', 'help': "check against these patches, in order (the default)"},
+    ),
     ('path', ('--path',), {'dest': 'path', 'help': "nest only this directory of upstream, at the root of <subdir>"}),
     ('pin', ('--pin',), {'dest': 'pin', 'help': "nest this commit or tag of the branch, not its newest commit"}),
     ('msg_file', ('--file',), {'dest': 'msg_file', 'help': "file to read the commit message from"}),
     ('tag', ('--tag',), {'dest': 'tag', 'help': "tag the pushed upstream commit with this name"}),
+    (
+        'output_dir',
+        ('-o', '--output'),
+        {
+            'dest': 'output_dir',
+            'help': "patches: folder for the missing patch; diff: file for the whole diff",
+        },
+    ),
+    (
+        'abort',
+        ('--abort',),
+        {'action': 'store_true', 'help': "throw away a 'submodules update' that stopped on conflicts"},
+    ),
+    (
+        'resume',
+        ('--continue',),
+        {'action': 'store_true', 'dest': 'resume', 'help': "finish a 'submodules update' that stopped on conflicts"},
+    ),
     ('remote', ('-r', '--remote'), {'dest': 'remote', 'help': "upstream remote to push/pull/fetch"}),
     (
         'short',
@@ -199,7 +293,7 @@ SUBPARSER_ARG_SPECS: list[tuple[str, tuple[str, ...], dict]] = [
     (
         'single_commit',
         ('--single-commit',),
-        {'action': 'store_true', 'help': "with --all: one commit for all nested repositories"},
+        {'action': 'store_true', 'help': "one commit for all nested repositories"},
     ),
     (
         'squash',
@@ -226,6 +320,7 @@ SUPPORTED_OPT_ATTRS: list[tuple[str, str]] = [
     ('path', 'path'),
     ('pin', 'pin'),
     ('tag', 'tag'),
+    ('output_dir', 'output_dir'),
 ]
 
 # Most commands take the same first positional, so it gets the same text.
@@ -255,6 +350,24 @@ POSITIONALS: dict[str, list[tuple[str, dict]]] = {
     'diff': [('subdir', {'nargs': '?', 'help': _SUBDIR_HELP})],
     'fetch': [('subdir', {'nargs': '?', 'help': _SUBDIR_HELP})],
     'init': [('subdir', {'nargs': '?', 'help': "subdirectory to turn into a nested repository"})],
+    'patches': [
+        (
+            'action',
+            {
+                'choices': ['create', 'verify', 'drop', 'cherry-pick'],
+                'help': "create: write; verify: check; drop: remove patches; cherry-pick: add commits or patch files",
+            },
+        ),
+        ('subdir', {'nargs': '?', 'help': _SUBDIR_HELP}),
+        (
+            'patch_names',
+            {
+                'nargs': '*',
+                'metavar': 'patch',
+                'help': "drop: the patches, by path or file name; cherry-pick: commits or patch files",
+            },
+        ),
+    ],
     'pull': [('subdir', {'nargs': '?', 'help': _SUBDIR_HELP})],
     'push': [
         ('subdir', {'nargs': '?', 'help': _SUBDIR_HELP}),
@@ -267,6 +380,21 @@ POSITIONALS: dict[str, list[tuple[str, dict]]] = {
         # everything after <subdir> goes to git untouched, options included.
         ('git_args', {'nargs': '...', 'help': "the git command to run, with its arguments"}),
     ],
+    'submodules': [
+        (
+            'submodules_action',
+            {'metavar': 'action', 'choices': ['init', 'update'], 'help': "init or update"},
+        ),
+        (
+            'submodules_args',
+            {
+                'metavar': 'arg',
+                'nargs': '*',
+                'help': "update: the commit to merge",
+            },
+        ),
+    ],
+    'verify': [('subdir', {'help': _SUBDIR_HELP})],
 }
 
 # The paragraph `git nested <command> --help` opens with. COMMAND_HELP is
@@ -321,6 +449,14 @@ COMMAND_DESCRIPTION: dict[str, str] = {
         "The files are left as they are. Without --remote the subdirectory has no upstream yet, "
         "which you can add later with 'git nested config'."
     ),
+    'patches': (
+        "Keep the local changes of <subdir> as patch files, in the patches folder of .gitnested. "
+        "create writes the changes that are not in a patch yet as a new patch, with a TODO title, "
+        "and writes all patches again in the one form git-nested uses. "
+        "verify only checks: it fails if a change is not in a patch, or if create would change a patch. "
+        "drop removes patches and their changes from <subdir>, writes the other patches again and commits. "
+        "cherry-pick adds commits (fetched from the remote if needed) or patch files as patches, and commits."
+    ),
     'pull': (
         "Fetch the upstream of <subdir> and join the new commits into it, by merge or by rebase. "
         "By default the result is one parent commit; --no-squash keeps the upstream commits as a merged second-parent history. "
@@ -348,6 +484,28 @@ COMMAND_DESCRIPTION: dict[str, str] = {
         "Report every nested repository in this repository: where it comes from, and whether it has local changes. "
         "With -q, just the paths, one per line."
     ),
+    'submodules': (
+        "Turn the submodules of a repository into plain files. "
+        "Each submodule becomes a nested repository. "
+        "The repository itself stays a normal git clone of its upstream. "
+        "'init' nests all submodules at the commits they pin, one commit each. "
+        "With --recursive, their submodules too. "
+        "--only and --ignore pick some of them. "
+        "A relative submodule url needs --resolve-relative. "
+        "'update' merges an upstream commit and keeps its commits. It does not fetch. "
+        "Then it changes the nested repositories the way upstream changed its submodules. "
+        "Each changed submodule gets one commit. "
+        "On conflicts, fix them and run --continue. Or give up with --abort. "
+        "--dry-run shows the changes and makes none."
+    ),
+    'verify': (
+        "Apply the files to the upstream commit in .gitnested, in a temporary worktree, and compare "
+        "the result with <subdir>. Patches go in with git am; plain diffs need --diffs. "
+        "Without files, check that <subdir> has no local changes. "
+        "If it differs, the command fails. With patches, it then writes the missing patch next to the last one "
+        "(or into --output). With --diffs, it writes the whole diff to --output. "
+        "For the patches folder of .gitnested, use 'git nested patches'."
+    ),
     'version': "Print the git-nested version, and the versions of git and Python it is running on.",
 }
 
@@ -397,11 +555,21 @@ COMMAND_EXAMPLES: dict[str, list[str]] = {
         "git nested init -r https://github.com/user/lib --commit abc123 ext/lib",
         "git nested init -r https://github.com/user/lib -b main ext/lib",
     ],
+    'patches': [
+        "git nested patches create ext/lib",
+        "git nested patches verify ext/lib",
+        "git nested patches verify --all",
+        "git nested patches drop ext/lib 0002-Old-workaround.patch",
+        "git nested patches cherry-pick ext/lib a1b2c3d",
+        "git nested patches cherry-pick -r https://github.com/fork/lib --local ext/lib refs/pull/42/head",
+        "git nested patches cherry-pick ext/lib ~/fix-build.patch",
+    ],
     'pull': [
         "git nested pull ext/lib",
         "git nested pull --no-squash ext/lib",
         "git nested pull -M rebase ext/lib",
         "git nested pull --rebase ext/lib",
+        "git nested pull --ignore ext/lib/tests ext/lib",
         "git nested pull --all",
         "git nested pull --all -b release/2.0",
     ],
@@ -410,6 +578,7 @@ COMMAND_EXAMPLES: dict[str, list[str]] = {
         "git nested push --dry-run ext/lib",
         "git nested push --rebase ext/lib",
         "git nested push --squash -m 'one commit upstream' ext/lib",
+        "git nested push --ignore ext/lib/local ext/lib",
         "git nested push --all -b release/2.0",
     ],
     'repair': [
@@ -424,6 +593,23 @@ COMMAND_EXAMPLES: dict[str, list[str]] = {
         "git nested status",
         "git nested status -q",
     ],
+    'submodules': [
+        "git nested submodules init",
+        "git nested submodules init --recursive",
+        "git nested submodules init --only lib/core",
+        "git nested submodules init --resolve-relative https://github.com/org/project",
+        "git nested submodules update upstream/main",
+        "git nested submodules update --dry-run upstream/main",
+        "git nested submodules update v2.0",
+        "git nested submodules update --continue",
+    ],
+    'verify': [
+        "git nested verify ext/lib --patches patches/lib/*.patch",
+        "git nested verify -o patches/lib ext/lib",
+        "git nested verify ext/lib --diffs lib.diff",
+        "git nested verify -o lib.diff ext/lib --diffs lib.diff",
+        "git nested verify --ignore ext/lib/build ext/lib",
+    ],
     'version': [
         "git nested version",
     ],

git_nested/commands/__init__.py

@@ -26,11 +26,14 @@ from . import (
     diff,
     fetch,
     init,
+    patchset,
     pull,
     push,
     repair,
     run,
     status,
+    submodules,
+    verify,
     version,
 )
 
@@ -44,10 +47,13 @@ REGISTRY: dict[str, Callable[[CommandContext], None]] = {
     'diff': diff.cmd_diff,
     'fetch': fetch.cmd_fetch,
     'init': init.cmd_init,
+    'patches': patchset.cmd_patches,
     'pull': pull.cmd_pull,
     'push': push.cmd_push,
     'repair': repair.cmd_repair,
     'run': run.cmd_run,
     'status': status.cmd_status,
+    'submodules': submodules.cmd_submodules,
+    'verify': verify.cmd_verify,
     'version': version.cmd_version,
 }