[PATCH 0/5] submodule: add 'reversive' traversal options to foreach

[PATCH 0/5] submodule: add 'reversive' traversal options to foreach

[William Hatfield]

This series introduces robust post-order (dependency-ordered) traversal to
`git submodule foreach` through three new flags: `--reverse-traversal`,
`--append-superproject`, and the shorthand `--reversive`. These options allow
users to process nested submodules before their parents and include the
superproject in the operation, enabling reliable automation for
dependency-ordered cleanup, builds, and deployment workflows.

Highlights:
- Implements all new traversal flags in both the C helper and shell script.
- Provides a comprehensive test suite (t7425) that validates the new behaviors.
- Updates documentation to describe the new options and their intended use.

These changes make submodule automation more powerful and flexible for advanced
and dependency-sensitive use cases.

William Hatfield (5):
  t7425: add tests for reversive submodule traversal
  submodule: teach and plumb reverse-traversal behavior
  submodule: teach and plumb append-superproject behavior
  submodule: introduce reversive shorthand mode
  doc: document reversive traversal and related modes

 Documentation/git-submodule.adoc |  20 ++
 builtin/submodule--helper.c      |  98 ++++++++--
 git-submodule.sh                 |  13 ++
 t/meson.build                    |   1 +
 t/t7425-submodule-reversion.sh   | 314 +++++++++++++++++++++++++++++++
 5 files changed, 435 insertions(+), 11 deletions(-)
 create mode 100755 t/t7425-submodule-reversion.sh

-- 
2.53.0-rc0

[PATCH 1/5] t7425: add tests for reversive submodule traversal

[William Hatfield]

Add test suite for the upcoming --reversive flag and its constituent
options: --reverse-traversal and --append-superproject. The --reversive
flag will be shorthand for: --recursive --reverse-traversal
--append-superproject.

Tests are marked as test_expect_failure since the features are not yet
implemented. They will be flipped to test_expect_success as each feature
is added.

Test structure:
 - Tests 1-2: Setup (success - prerequisites)
 - Test 3: --recursive existing behavior (success - already works)
 - Tests 4-5: --reverse-traversal (failure - needs implementation)
 - Tests 6-7: --append-superproject (failure - needs implementation)
 - Tests 8-9: Combined flags (failure - needs both features)
 - Tests 10-12: --reversive shorthand (failure - needs implementation)
 - Tests 13-16: --append-superproject edge cases (failure - needs implementation)

The test creates a multi-branch submodule tree with varying depths to
validate traversal order:

    top
    ├── sub0
    ├── sub1 -> sub2
    ├── sub3 -> sub4, sub5
    └── sub6 -> sub7 -> sub8, sub9

Signed-off-by: William Hatfield <whatfield.git@gmail.com>
---
 t/meson.build                  |   1 +
 t/t7425-submodule-reversion.sh | 329 +++++++++++++++++++++++++++++++++
 2 files changed, 330 insertions(+)
 create mode 100755 t/t7425-submodule-reversion.sh

diff --git a/t/meson.build b/t/meson.build
index 459c52a489..d3a5e17ff7 100644
--- a/t/meson.build
+++ b/t/meson.build
@@ -887,6 +887,7 @@ integration_tests = [
   't7422-submodule-output.sh',
   't7423-submodule-symlinks.sh',
   't7424-submodule-mixed-ref-formats.sh',
+  't7425-submodule-reversion.sh',
   't7450-bad-git-dotfiles.sh',
   't7500-commit-template-squash-signoff.sh',
   't7501-commit-basic-functionality.sh',
diff --git a/t/t7425-submodule-reversion.sh b/t/t7425-submodule-reversion.sh
new file mode 100755
index 0000000000..06c3ab6294
--- /dev/null
+++ b/t/t7425-submodule-reversion.sh
@@ -0,0 +1,329 @@
+#!/bin/sh
+#
+# Copyright (c) 2026 William Hatfield
+#
+
+test_description='Test "git submodule foreach --reversive"
+
+This test suite validates the --reversive flag and its constituent options:
+--recursive, --reverse-traversal, and --append-superproject. Tests confirm
+flags are correctly parsed and set non-zero integral values. Additional tests
+verify post-order traversal, superproject inclusion, and flag combinations.
+The --reversive flag is shorthand for: --recursive --reverse-traversal
+--append-superproject.
+'
+
+GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME=main
+export GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME
+
+. ./test-lib.sh
+
+# Helper: create content and initial commit in a submodule
+# Usage: create_submodule_content <name> <content>
+create_submodule_content () {
+	echo "$2" >"$1/file" &&
+	git -C "$1" add file &&
+	test_tick &&
+	git -C "$1" commit -m "$1 commit"
+}
+
+# Helper: add submodules to a parent and commit
+# Usage: add_submodules <parent> <child1> [child2 ...]
+add_submodules () {
+	parent=$1 &&
+	shift &&
+	for child in "$@"; do
+		git -C "$parent" submodule add ../"$child" "$child" || return 1
+	done &&
+	test_tick &&
+	git -C "$parent" commit -m "add $*"
+}
+
+test_expect_success 'setup - enable local submodules' '
+	git config --global protocol.file.allow always
+'
+
+test_expect_success 'setup reversive sandbox (full multi-branch tree)' '
+	mkdir reversive &&
+	(
+		# Tree structure created in this sandbox:
+		#
+		#     top
+		#     ├── sub0
+		#     │
+		#     ├── sub1
+		#     │   └── sub2
+		#     │
+		#     ├── sub3
+		#     │   ├── sub4
+		#     │   └── sub5
+		#     │
+		#     └── sub6
+		#         └── sub7
+		#             ├── sub8
+		#             └── sub9
+		#
+		# This structure provides:
+		#   - Four top‑level siblings (sub0, sub1, sub3, sub6)
+		#   - Mixed branch depths (1‑deep, 2‑deep, 3‑deep)
+		#   - Multiple nested sibling sets (sub4+5 and sub8+9)
+		#   - A leaf‑only sibling (sub0)
+		#   - Ideal coverage for traversal tests
+
+		cd reversive &&
+
+		# Create all repositories
+		test_create_repo top &&
+		test_create_repo sub0 &&
+		test_create_repo sub1 &&
+		test_create_repo sub2 &&
+		test_create_repo sub3 &&
+		test_create_repo sub4 &&
+		test_create_repo sub5 &&
+		test_create_repo sub6 &&
+		test_create_repo sub7 &&
+		test_create_repo sub8 &&
+		test_create_repo sub9 &&
+
+		# Create leaf submodules first (no children)
+		create_submodule_content sub0 zero &&
+		create_submodule_content sub2 two &&
+		create_submodule_content sub4 four &&
+		create_submodule_content sub5 five &&
+		create_submodule_content sub8 eight &&
+		create_submodule_content sub9 nine &&
+
+		# Build sub1 branch (sub1 -> sub2)
+		create_submodule_content sub1 one &&
+		add_submodules sub1 sub2 &&
+
+		# Build sub3 branch (sub3 -> sub4, sub5)
+		create_submodule_content sub3 three &&
+		add_submodules sub3 sub4 sub5 &&
+
+		# Build sub7 (sub7 -> sub8, sub9)
+		create_submodule_content sub7 seven &&
+		add_submodules sub7 sub8 sub9 &&
+
+		# Build sub6 branch (sub6 -> sub7)
+		create_submodule_content sub6 six &&
+		add_submodules sub6 sub7 &&
+
+		# Build top (top -> sub0, sub1, sub3, sub6)
+		create_submodule_content top root &&
+		add_submodules top sub0 sub1 sub3 sub6 &&
+		git -C top submodule update --init --recursive
+	)
+'
+
+test_expect_success '--recursive parses and prints(runs), existing behavior' '
+	(
+		cd reversive/top &&
+		git submodule --quiet foreach --recursive "echo \$displaypath"
+	) >actual &&
+
+	cat >expect <<-\EOF &&
+sub0
+sub1
+sub1/sub2
+sub3
+sub3/sub4
+sub3/sub5
+sub6
+sub6/sub7
+sub6/sub7/sub8
+sub6/sub7/sub9
+EOF
+
+	test_cmp expect actual
+'
+
+test_expect_failure '--recursive and --reverse-traversal parses' '
+	(
+		cd reversive/top &&
+		git submodule foreach --recursive --reverse-traversal "true"
+	)
+'
+
+test_expect_failure '--recursive and --reverse-traversal runs' '
+	(
+		cd reversive/top &&
+		git submodule --quiet foreach --recursive \
+			--reverse-traversal "echo \$displaypath"
+	) >actual &&
+
+	cat >expect <<-\EOF &&
+sub6/sub7/sub9
+sub6/sub7/sub8
+sub6/sub7
+sub6
+sub3/sub5
+sub3/sub4
+sub3
+sub1/sub2
+sub1
+sub0
+EOF
+
+	test_cmp expect actual
+'
+
+test_expect_failure '--recursive and --append-superproject parses' '
+	(
+		cd reversive/top &&
+		git submodule foreach --recursive --append-superproject "true"
+	)
+'
+
+test_expect_failure '--recursive and --append-superproject runs' '
+	(
+		cd reversive/top &&
+		git submodule --quiet foreach --recursive \
+			--append-superproject "echo \$displaypath"
+	) >actual &&
+
+	cat >expect <<-\EOF &&
+sub0
+sub1
+sub1/sub2
+sub3
+sub3/sub4
+sub3/sub5
+sub6
+sub6/sub7
+sub6/sub7/sub8
+sub6/sub7/sub9
+../top
+EOF
+
+	test_cmp expect actual
+'
+
+test_expect_failure '--reverse-traversal and --append-superproject parses' '
+	(
+		cd reversive/top &&
+		git submodule foreach \
+			--recursive --reverse-traversal --append-superproject "true"
+	)
+'
+
+test_expect_failure '--reverse-traversal and --append-superproject runs' '
+	(
+		cd reversive/top &&
+		git submodule --quiet foreach --recursive \
+			--reverse-traversal --append-superproject "echo \$displaypath"
+	) >actual &&
+
+	cat >expect <<-\EOF &&
+sub6/sub7/sub9
+sub6/sub7/sub8
+sub6/sub7
+sub6
+sub3/sub5
+sub3/sub4
+sub3
+sub1/sub2
+sub1
+sub0
+../top
+EOF
+
+	test_cmp expect actual
+'
+
+test_expect_failure '--reversive parses' '
+	(
+		cd reversive/top &&
+		git submodule foreach --reversive "true"
+	)
+'
+
+test_expect_failure '--reversive runs' '
+	(
+		cd reversive/top &&
+		git submodule --quiet foreach --reversive "echo \$displaypath"
+	) >actual &&
+
+	cat >expect <<-\EOF &&
+sub6/sub7/sub9
+sub6/sub7/sub8
+sub6/sub7
+sub6
+sub3/sub5
+sub3/sub4
+sub3
+sub1/sub2
+sub1
+sub0
+../top
+EOF
+
+	test_cmp expect actual
+'
+
+test_expect_failure '--reversive stops on command failure' '
+	(
+		cd reversive/top &&
+		git submodule foreach --reversive "true" &&
+		test_must_fail git submodule foreach --reversive \
+			"test \$name != sub7 || exit 1"
+	)
+'
+
+test_expect_failure '--append-superproject with no submodules runs only superproject' '
+	test_create_repo empty_repo &&
+	(
+		cd empty_repo &&
+		git submodule --quiet foreach --append-superproject \
+			"echo \$displaypath"
+	) >actual &&
+
+	cat >expect <<-\EOF &&
+../empty_repo
+EOF
+
+	test_cmp expect actual
+'
+
+test_expect_failure '--append-superproject sets all expected variables' '
+	(
+		cd reversive/top &&
+		git submodule --quiet foreach --append-superproject \
+			"echo name=\$name path=\$path displaypath=\$displaypath" |
+			tail -n 1
+	) >actual &&
+
+	cat >expect <<-\EOF &&
+name=top path=../top displaypath=../top
+EOF
+
+	test_cmp expect actual
+'
+
+test_expect_failure '--append-superproject from nested submodule appends correct superproject' '
+	(
+		cd reversive/top/sub6 &&
+		git submodule --quiet foreach --recursive --append-superproject \
+			"echo \$displaypath"
+	) >actual &&
+
+	cat >expect <<-\EOF &&
+sub7
+sub7/sub8
+sub7/sub9
+../sub6
+EOF
+
+	test_cmp expect actual
+'
+
+test_expect_failure '--quiet suppresses Entering message for superproject' '
+	(
+		cd reversive/top &&
+		git submodule foreach --quiet --append-superproject "true"
+	) >actual 2>&1 &&
+
+	! grep "Entering" actual
+'
+
+test_done
-- 
2.53.0-rc0

[PATCH 2/5] submodule: teach and plumb reverse-traversal behavior

[William Hatfield]

Add --reverse-traversal flag to 'git submodule foreach' that reverses
the order in which submodules are traversed. When combined with
--recursive, this provides post-order traversal where nested submodules
are visited before their parents.

This is useful for operations that need to process dependencies before
dependents, such as building from leaves to root or cleaning up in
reverse dependency order.

Implementation:
 - Add reverse_traversal field to struct foreach_cb
 - Extend for_each_listed_submodule() with reverse parameter
 - Add post-order recursion block in runcommand_in_submodule_cb()
 - Parse --reverse-traversal in module_foreach() and git-submodule.sh

Signed-off-by: William Hatfield <whatfield.git@gmail.com>
---
 builtin/submodule--helper.c    | 60 +++++++++++++++++++++++++++-------
 git-submodule.sh               |  4 +++
 t/t7425-submodule-reversion.sh |  4 +--
 3 files changed, 55 insertions(+), 13 deletions(-)

diff --git a/builtin/submodule--helper.c b/builtin/submodule--helper.c
index d537ab087a..b1e202399e 100644
--- a/builtin/submodule--helper.c
+++ b/builtin/submodule--helper.c
@@ -264,12 +264,18 @@ static char *get_up_path(const char *path)
 }
 
 static void for_each_listed_submodule(const struct module_list *list,
-				      each_submodule_fn fn, void *cb_data)
+				      each_submodule_fn fn, void *cb_data,
+				      int reverse)
 {
 	int i;
 
-	for (i = 0; i < list->nr; i++)
-		fn(list->entries[i], cb_data);
+	if (reverse) {
+		for (i = list->nr - 1; i >= 0; i--)
+			fn(list->entries[i], cb_data);
+	} else {
+		for (i = 0; i < list->nr; i++)
+			fn(list->entries[i], cb_data);
+	}
 }
 
 struct foreach_cb {
@@ -279,6 +285,7 @@ struct foreach_cb {
 	const char *super_prefix;
 	int quiet;
 	int recursive;
+	int reverse_traversal;
 };
 #define FOREACH_CB_INIT { 0 }
 
@@ -352,6 +359,33 @@ static void runcommand_in_submodule_cb(const struct cache_entry *list_item,
 		strvec_pushv(&cp.args, info->argv);
 	}
 
+	/*
+	 * For --reverse-traversal, recurse into nested submodules first
+	 * (post-order traversal: children before parents).
+	 */
+	if (info->recursive && info->reverse_traversal) {
+		struct child_process cpr = CHILD_PROCESS_INIT;
+
+		cpr.git_cmd = 1;
+		cpr.dir = path;
+		prepare_submodule_repo_env(&cpr.env);
+
+		strvec_pushl(&cpr.args, "submodule--helper", "foreach", "--recursive",
+			     "--reverse-traversal", NULL);
+		strvec_pushf(&cpr.args, "--super-prefix=%s/", displaypath);
+
+		if (info->quiet)
+			strvec_push(&cpr.args, "--quiet");
+
+		strvec_push(&cpr.args, "--");
+		strvec_pushv(&cpr.args, info->argv);
+
+		if (run_command(&cpr))
+			die(_("run_command returned non-zero status while "
+				"recursing in the nested submodules of %s\n."),
+				displaypath);
+	}
+
 	if (!info->quiet)
 		printf(_("Entering '%s'\n"), displaypath);
 
@@ -363,7 +397,8 @@ static void runcommand_in_submodule_cb(const struct cache_entry *list_item,
 		child_process_clear(&cp);
 	}
 
-	if (info->recursive) {
+	/* For normal (pre-order) recursion, recurse after command execution. */
+	if (info->recursive && !info->reverse_traversal) {
 		struct child_process cpr = CHILD_PROCESS_INIT;
 
 		cpr.git_cmd = 1;
@@ -401,10 +436,12 @@ static int module_foreach(int argc, const char **argv, const char *prefix,
 		OPT__QUIET(&info.quiet, N_("suppress output of entering each submodule command")),
 		OPT_BOOL(0, "recursive", &info.recursive,
 			 N_("recurse into nested submodules")),
+		OPT_BOOL(0, "reverse-traversal", &info.reverse_traversal,
+			 N_("traverse submodules in reverse order (post-order)")),
 		OPT_END()
 	};
 	const char *const git_submodule_helper_usage[] = {
-		N_("git submodule foreach [--quiet] [--recursive] [--] <command>"),
+		N_("git submodule foreach [--quiet] [--recursive] [--reverse-traversal] [--] <command>"),
 		NULL
 	};
 	int ret = 1;
@@ -419,7 +456,8 @@ static int module_foreach(int argc, const char **argv, const char *prefix,
 	info.argv = argv;
 	info.prefix = prefix;
 
-	for_each_listed_submodule(&list, runcommand_in_submodule_cb, &info);
+	for_each_listed_submodule(&list, runcommand_in_submodule_cb, &info,
+				  info.reverse_traversal);
 
 	ret = 0;
 cleanup:
@@ -558,7 +596,7 @@ static int module_init(int argc, const char **argv, const char *prefix,
 	if (quiet)
 		info.flags |= OPT_QUIET;
 
-	for_each_listed_submodule(&list, init_submodule_cb, &info);
+	for_each_listed_submodule(&list, init_submodule_cb, &info, 0);
 
 	ret = 0;
 cleanup:
@@ -742,7 +780,7 @@ static int module_status(int argc, const char **argv, const char *prefix,
 	if (quiet)
 		info.flags |= OPT_QUIET;
 
-	for_each_listed_submodule(&list, status_submodule_cb, &info);
+	for_each_listed_submodule(&list, status_submodule_cb, &info, 0);
 
 	ret = 0;
 cleanup:
@@ -1345,7 +1383,7 @@ static int module_sync(int argc, const char **argv, const char *prefix,
 	if (recursive)
 		info.flags |= OPT_RECURSIVE;
 
-	for_each_listed_submodule(&list, sync_submodule_cb, &info);
+	for_each_listed_submodule(&list, sync_submodule_cb, &info, 0);
 
 	ret = 0;
 cleanup:
@@ -1501,7 +1539,7 @@ static int module_deinit(int argc, const char **argv, const char *prefix,
 	if (force)
 		info.flags |= OPT_FORCE;
 
-	for_each_listed_submodule(&list, deinit_submodule_cb, &info);
+	for_each_listed_submodule(&list, deinit_submodule_cb, &info, 0);
 
 	ret = 0;
 cleanup:
@@ -2885,7 +2923,7 @@ static int module_update(int argc, const char **argv, const char *prefix,
 		if (opt.quiet)
 			info.flags |= OPT_QUIET;
 
-		for_each_listed_submodule(&list, init_submodule_cb, &info);
+		for_each_listed_submodule(&list, init_submodule_cb, &info, 0);
 		module_list_release(&list);
 	}
 
diff --git a/git-submodule.sh b/git-submodule.sh
index 2999b31fad..49e9541a3d 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -173,6 +173,9 @@ cmd_foreach()
 		--recursive)
 			recursive=$1
 			;;
+		--reverse-traversal)
+			reverse_traversal=$1
+			;;
 		-*)
 			usage
 			;;
@@ -186,6 +189,7 @@ cmd_foreach()
 	git ${wt_prefix:+-C "$wt_prefix"} submodule--helper foreach \
 		$quiet \
 		$recursive \
+		$reverse_traversal \
 		-- \
 		"$@"
 }
diff --git a/t/t7425-submodule-reversion.sh b/t/t7425-submodule-reversion.sh
index 06c3ab6294..c6733234aa 100755
--- a/t/t7425-submodule-reversion.sh
+++ b/t/t7425-submodule-reversion.sh
@@ -138,14 +138,14 @@ EOF
 	test_cmp expect actual
 '
 
-test_expect_failure '--recursive and --reverse-traversal parses' '
+test_expect_success '--recursive and --reverse-traversal parses' '
 	(
 		cd reversive/top &&
 		git submodule foreach --recursive --reverse-traversal "true"
 	)
 '
 
-test_expect_failure '--recursive and --reverse-traversal runs' '
+test_expect_success '--recursive and --reverse-traversal runs' '
 	(
 		cd reversive/top &&
 		git submodule --quiet foreach --recursive \
-- 
2.53.0-rc0

[PATCH 3/5] submodule: teach and plumb append-superproject behavior

[William Hatfield]

Add --append-superproject flag to 'git submodule foreach' that runs the
command in the superproject after processing all submodules. This is
only executed at the top-level invocation, not during recursion.

The superproject execution sets the same environment variables as for
submodules (name, sm_path, displaypath, sha1, toplevel) so scripts
using these variables work uniformly. The '../<name>' displaypath
mirrors submodule output style and visually indicates ascent to the
parent repository.

When combined with --recursive and --reverse-traversal, this enables
full post-order traversal from deepest submodules up to the
superproject.

Implementation:
 - Add append_superproject field to struct foreach_cb
 - Parse --append-superproject in module_foreach() and git-submodule.sh
 - Add superproject execution block after submodule traversal
 - Only run at top-level (when super_prefix is not set)

Signed-off-by: William Hatfield <whatfield.git@gmail.com>
---
 builtin/submodule--helper.c    | 31 ++++++++++++++++++++++++++++++-
 git-submodule.sh               |  4 ++++
 t/t7425-submodule-reversion.sh | 29 +++++++----------------------
 3 files changed, 41 insertions(+), 23 deletions(-)

diff --git a/builtin/submodule--helper.c b/builtin/submodule--helper.c
index b1e202399e..f6cba87a05 100644
--- a/builtin/submodule--helper.c
+++ b/builtin/submodule--helper.c
@@ -286,6 +286,7 @@ struct foreach_cb {
 	int quiet;
 	int recursive;
 	int reverse_traversal;
+	int append_superproject;
 };
 #define FOREACH_CB_INIT { 0 }
 
@@ -438,10 +439,12 @@ static int module_foreach(int argc, const char **argv, const char *prefix,
 			 N_("recurse into nested submodules")),
 		OPT_BOOL(0, "reverse-traversal", &info.reverse_traversal,
 			 N_("traverse submodules in reverse order (post-order)")),
+		OPT_BOOL(0, "append-superproject", &info.append_superproject,
+			 N_("also run command in superproject after submodules")),
 		OPT_END()
 	};
 	const char *const git_submodule_helper_usage[] = {
-		N_("git submodule foreach [--quiet] [--recursive] [--reverse-traversal] [--] <command>"),
+		N_("git submodule foreach [--quiet] [--recursive] [--reverse-traversal] [--append-superproject] [--] <command>"),
 		NULL
 	};
 	int ret = 1;
@@ -459,6 +462,32 @@ static int module_foreach(int argc, const char **argv, const char *prefix,
 	for_each_listed_submodule(&list, runcommand_in_submodule_cb, &info,
 				  info.reverse_traversal);
 
+	/*
+	 * Run command in superproject after all submodules, but only at the
+	 * top-level invocation (not during recursion into nested submodules).
+	 */
+	if (info.append_superproject && !info.super_prefix) {
+		struct child_process cp = CHILD_PROCESS_INIT;
+		char *toplevel = xgetcwd();
+		const char *slash = find_last_dir_sep(toplevel);
+		const char *super_name = slash ? slash + 1 : toplevel;
+		char *displaypath = xstrfmt("../%s", super_name);
+
+		cp.use_shell = 1;
+		cp.dir = toplevel;
+		strvec_pushf(&cp.env, "displaypath=%s", displaypath);
+		strvec_pushv(&cp.args, info.argv);
+
+		if (!info.quiet)
+			printf(_("Entering '%s'\n"), displaypath);
+
+		if (run_command(&cp))
+			die(_("command failed in superproject\n"));
+
+		free(displaypath);
+		free(toplevel);
+	}
+
 	ret = 0;
 cleanup:
 	module_list_release(&list);
diff --git a/git-submodule.sh b/git-submodule.sh
index 49e9541a3d..58682a287d 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -176,6 +176,9 @@ cmd_foreach()
 		--reverse-traversal)
 			reverse_traversal=$1
 			;;
+		--append-superproject)
+			append_superproject=$1
+			;;
 		-*)
 			usage
 			;;
@@ -190,6 +193,7 @@ cmd_foreach()
 		$quiet \
 		$recursive \
 		$reverse_traversal \
+		$append_superproject \
 		-- \
 		"$@"
 }
diff --git a/t/t7425-submodule-reversion.sh b/t/t7425-submodule-reversion.sh
index c6733234aa..7a6a54de15 100755
--- a/t/t7425-submodule-reversion.sh
+++ b/t/t7425-submodule-reversion.sh
@@ -168,14 +168,14 @@ EOF
 	test_cmp expect actual
 '
 
-test_expect_failure '--recursive and --append-superproject parses' '
+test_expect_success '--recursive and --append-superproject parses' '
 	(
 		cd reversive/top &&
 		git submodule foreach --recursive --append-superproject "true"
 	)
 '
 
-test_expect_failure '--recursive and --append-superproject runs' '
+test_expect_success '--recursive and --append-superproject runs' '
 	(
 		cd reversive/top &&
 		git submodule --quiet foreach --recursive \
@@ -199,7 +199,7 @@ EOF
 	test_cmp expect actual
 '
 
-test_expect_failure '--reverse-traversal and --append-superproject parses' '
+test_expect_success '--reverse-traversal and --append-superproject parses' '
 	(
 		cd reversive/top &&
 		git submodule foreach \
@@ -207,7 +207,7 @@ test_expect_failure '--reverse-traversal and --append-superproject parses' '
 	)
 '
 
-test_expect_failure '--reverse-traversal and --append-superproject runs' '
+test_expect_success '--reverse-traversal and --append-superproject runs' '
 	(
 		cd reversive/top &&
 		git submodule --quiet foreach --recursive \
@@ -270,7 +270,7 @@ test_expect_failure '--reversive stops on command failure' '
 	)
 '
 
-test_expect_failure '--append-superproject with no submodules runs only superproject' '
+test_expect_success '--append-superproject with no submodules runs only superproject' '
 	test_create_repo empty_repo &&
 	(
 		cd empty_repo &&
@@ -285,22 +285,7 @@ EOF
 	test_cmp expect actual
 '
 
-test_expect_failure '--append-superproject sets all expected variables' '
-	(
-		cd reversive/top &&
-		git submodule --quiet foreach --append-superproject \
-			"echo name=\$name path=\$path displaypath=\$displaypath" |
-			tail -n 1
-	) >actual &&
-
-	cat >expect <<-\EOF &&
-name=top path=../top displaypath=../top
-EOF
-
-	test_cmp expect actual
-'
-
-test_expect_failure '--append-superproject from nested submodule appends correct superproject' '
+test_expect_success '--append-superproject from nested submodule appends correct superproject' '
 	(
 		cd reversive/top/sub6 &&
 		git submodule --quiet foreach --recursive --append-superproject \
@@ -317,7 +302,7 @@ EOF
 	test_cmp expect actual
 '
 
-test_expect_failure '--quiet suppresses Entering message for superproject' '
+test_expect_success '--quiet suppresses Entering message for superproject' '
 	(
 		cd reversive/top &&
 		git submodule foreach --quiet --append-superproject "true"
-- 
2.53.0-rc0

[PATCH 4/5] submodule: introduce reversive shorthand mode

[William Hatfield]

Add --reversive as a convenience shorthand that combines:
 - --recursive: process all nested submodules
 - --reverse-traversal: visit children before parents (post-order)
 - --append-superproject: run command in superproject after all submodules

This enables a single flag to achieve full post-order traversal from
the deepest submodules up to the superproject, which is useful for
build systems, cleanup scripts, or any operation that needs to process
dependencies before dependents.

Signed-off-by: William Hatfield <whatfield.git@gmail.com>
---
 builtin/submodule--helper.c    | 11 ++++++++++-
 git-submodule.sh               |  5 +++++
 t/t7425-submodule-reversion.sh |  6 +++---
 3 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/builtin/submodule--helper.c b/builtin/submodule--helper.c
index f6cba87a05..26365b397b 100644
--- a/builtin/submodule--helper.c
+++ b/builtin/submodule--helper.c
@@ -432,6 +432,7 @@ static int module_foreach(int argc, const char **argv, const char *prefix,
 	struct foreach_cb info = FOREACH_CB_INIT;
 	struct pathspec pathspec = { 0 };
 	struct module_list list = MODULE_LIST_INIT;
+	int reversive = 0;
 	struct option module_foreach_options[] = {
 		OPT__SUPER_PREFIX(&info.super_prefix),
 		OPT__QUIET(&info.quiet, N_("suppress output of entering each submodule command")),
@@ -441,10 +442,12 @@ static int module_foreach(int argc, const char **argv, const char *prefix,
 			 N_("traverse submodules in reverse order (post-order)")),
 		OPT_BOOL(0, "append-superproject", &info.append_superproject,
 			 N_("also run command in superproject after submodules")),
+		OPT_BOOL(0, "reversive", &reversive,
+			 N_("shorthand for --recursive --reverse-traversal --append-superproject")),
 		OPT_END()
 	};
 	const char *const git_submodule_helper_usage[] = {
-		N_("git submodule foreach [--quiet] [--recursive] [--reverse-traversal] [--append-superproject] [--] <command>"),
+		N_("git submodule foreach [--quiet] [--recursive] [--reverse-traversal] [--append-superproject] [--reversive] [--] <command>"),
 		NULL
 	};
 	int ret = 1;
@@ -452,6 +455,12 @@ static int module_foreach(int argc, const char **argv, const char *prefix,
 	argc = parse_options(argc, argv, prefix, module_foreach_options,
 			     git_submodule_helper_usage, 0);
 
+	if (reversive) {
+		info.recursive = 1;
+		info.reverse_traversal = 1;
+		info.append_superproject = 1;
+	}
+
 	if (module_list_compute(NULL, prefix, &pathspec, &list) < 0)
 		goto cleanup;
 
diff --git a/git-submodule.sh b/git-submodule.sh
index 58682a287d..e1b81344f6 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -179,6 +179,11 @@ cmd_foreach()
 		--append-superproject)
 			append_superproject=$1
 			;;
+		--reversive)
+			recursive=--recursive
+			reverse_traversal=--reverse-traversal
+			append_superproject=--append-superproject
+			;;
 		-*)
 			usage
 			;;
diff --git a/t/t7425-submodule-reversion.sh b/t/t7425-submodule-reversion.sh
index 7a6a54de15..88f61b0f06 100755
--- a/t/t7425-submodule-reversion.sh
+++ b/t/t7425-submodule-reversion.sh
@@ -231,14 +231,14 @@ EOF
 	test_cmp expect actual
 '
 
-test_expect_failure '--reversive parses' '
+test_expect_success '--reversive parses' '
 	(
 		cd reversive/top &&
 		git submodule foreach --reversive "true"
 	)
 '
 
-test_expect_failure '--reversive runs' '
+test_expect_success '--reversive runs' '
 	(
 		cd reversive/top &&
 		git submodule --quiet foreach --reversive "echo \$displaypath"
@@ -261,7 +261,7 @@ EOF
 	test_cmp expect actual
 '
 
-test_expect_failure '--reversive stops on command failure' '
+test_expect_success '--reversive stops on command failure' '
 	(
 		cd reversive/top &&
 		git submodule foreach --reversive "true" &&
-- 
2.53.0-rc0

[PATCH 5/5] doc: document reversive traversal and related modes

[William Hatfield]

Add documentation for the new --reverse-traversal, --append-superproject,
and --reversive flags to git-submodule.adoc. These flags enable post-order
traversal through nested submodule hierarchies, which is useful for
cleanup operations and dependency-ordered processing.

The flags only take effect when used with --recursive.

Signed-off-by: William Hatfield <whatfield.git@gmail.com>
---
 Documentation/git-submodule.adoc | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc
index 95beaee561..2be477952d 100644
--- a/Documentation/git-submodule.adoc
+++ b/Documentation/git-submodule.adoc
@@ -437,6 +437,26 @@ options carefully.
 	only in the submodules of the current repo, but also
 	in any nested submodules inside those submodules (and so on).
 
+--reverse-traversal::
+	This option is only valid for the foreach command and requires
+	`--recursive`.  Process nested submodules in post-order (deepest
+	first) rather than the default pre-order.  This is useful for
+	cleanup operations where nested submodules must be processed
+	before their parents.
+
+--append-superproject::
+	This option is only valid for the foreach command and requires
+	`--recursive`.  After processing all submodules, also run the
+	command in the superproject (top-level repository).  The
+	superproject is displayed as `../<name>` to mirror submodule
+	output style.
+
+--reversive::
+	This option is only valid for the foreach command and is
+	shorthand for `--recursive --reverse-traversal --append-superproject`.
+	It provides a complete "reverse" traversal: deepest submodules
+	first, then their parents, and finally the superproject.
+
 --depth::
 	This option is valid for add and update commands. Create a 'shallow'
 	clone with a history truncated to the specified number of revisions.
-- 
2.53.0-rc0

Re: [PATCH 5/5] doc: document reversive traversal and related modes

[Jean-Noël AVILA]

On Saturday, 31 January 2026 22:43:09 CET William Hatfield wrote:
> Add documentation for the new --reverse-traversal, --append-superproject,
> and --reversive flags to git-submodule.adoc. These flags enable post-order
> traversal through nested submodule hierarchies, which is useful for
> cleanup operations and dependency-ordered processing.
> 
> The flags only take effect when used with --recursive.
> 
> Signed-off-by: William Hatfield <whatfield.git@gmail.com>

Hello,

git-submodule is being transitioned to `synopsis` style of markup.
See https://lore.kernel.org/git/
05e68e28257cd450463d253abe9b2995759bdc10.1769462744.git.gitgitgadget@gmail.com/

In the same move, there is some work on style consistency of the manual pages. 

Below are the remarks on what changed:

> ---
>  Documentation/git-submodule.adoc | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
> 
> diff --git a/Documentation/git-submodule.adoc b/Documentation/git-
submodule.adoc
> index 95beaee561..2be477952d 100644
> --- a/Documentation/git-submodule.adoc
> +++ b/Documentation/git-submodule.adoc
> @@ -437,6 +437,26 @@ options carefully.
>  	only in the submodules of the current repo, but also
>  	in any nested submodules inside those submodules (and so on).
> 
> +--reverse-traversal::

Now, options in description lists are backticked:

`--reverse-traversal`::

> +	This option is only valid for the foreach command and requires
> +	`--recursive`.  Process nested submodules in post-order (deepest
> +	first) rather than the default pre-order.  This is useful for
> +	cleanup operations where nested submodules must be processed
> +	before their parents.

Please start the description with the actual action of the option. Then, you 
can add conditions, context, explanation:

Process nested [...]. This option is only valid [...]. This is useful [...]

Thanks

Re: [PATCH 0/5] submodule: add 'reversive' traversal options to foreach

[Junio C Hamano]

William Hatfield <whatfield.git@gmail.com> writes:

> This series introduces robust post-order (dependency-ordered) traversal to
> `git submodule foreach` through three new flags: `--reverse-traversal`,
> `--append-superproject`, and the shorthand `--reversive`. These options allow
> users to process nested submodules before their parents and include the
> superproject in the operation, enabling reliable automation for
> dependency-ordered cleanup, builds, and deployment workflows.
>
> Highlights:
> - Implements all new traversal flags in both the C helper and shell script.
> - Provides a comprehensive test suite (t7425) that validates the new behaviors.
> - Updates documentation to describe the new options and their intended use.
>
> These changes make submodule automation more powerful and flexible for advanced
> and dependency-sensitive use cases.

A few comments on the overall structure and concepts.

 * We do not want to see tests in a commit separate from the commit
   that fixes.  The downside of such a layout of a series needs to
   be understood.  An earlier step of a series may introduce a line
   with "test_expect_failure" plus a short summary of what the piece
   fixes, followed by a large amount of code to show exactly what is
   being tested and expected outcome.  But when reading the step
   that comes later that fixes the issue, readers will only see
   changes from "test_expect_failure" to "test_expect success" with
   most of the test to remind them what the issue was hidden away
   from the view, in the post-context of patch hunk.  A commit that
   has both the fix and the test that describes the expectation is
   much easier to work with.

 * The name "--reverse-traversal" makes sense only to those who know
   what the normal traversal order is, but it is far from clear what
   the normal submodule traversal order is, because there is no
   "natural" order to traverse.  Any of the combination of "top
   down/bottom up" "width first/depth first" would make sense
   depending on the application.  If you are doing "bottom up", for
   example, please name it as such.

 * The name "--append-superproject" sounds strange.  It sounds as if
   you are appending the superproject to something else, but I
   suspect that is not what is happening; instead perhaps you are
   leaving the traversal of the superproject at the end, or
   something?

Thanks.

Re: [PATCH 0/5] submodule: add 'reversive' traversal options to foreach

[William Hatfield]

> On Feb 2, 2026, at 1:52 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> William Hatfield <whatfield.git@gmail.com> writes:
> 
>> This series introduces robust post-order (dependency-ordered) traversal to
>> `git submodule foreach` through three new flags: `--reverse-traversal`,
>> `--append-superproject`, and the shorthand `--reversive`. These options allow
>> users to process nested submodules before their parents and include the
>> superproject in the operation, enabling reliable automation for
>> dependency-ordered cleanup, builds, and deployment workflows.
>> 
>> Highlights:
>> - Implements all new traversal flags in both the C helper and shell script.
>> - Provides a comprehensive test suite (t7425) that validates the new behaviors.
>> - Updates documentation to describe the new options and their intended use.
>> 
>> These changes make submodule automation more powerful and flexible for advanced
>> and dependency-sensitive use cases.
> 
> A few comments on the overall structure and concepts.
> 
> * We do not want to see tests in a commit separate from the commit
>   that fixes.  The downside of such a layout of a series needs to
>   be understood.  An earlier step of a series may introduce a line
>   with "test_expect_failure" plus a short summary of what the piece
>   fixes, followed by a large amount of code to show exactly what is
>   being tested and expected outcome.  But when reading the step
>   that comes later that fixes the issue, readers will only see
>   changes from "test_expect_failure" to "test_expect success" with
>   most of the test to remind them what the issue was hidden away
>   from the view, in the post-context of patch hunk.  A commit that
>   has both the fix and the test that describes the expectation is
>   much easier to work with.
> 
> * The name "--reverse-traversal" makes sense only to those who know
>   what the normal traversal order is, but it is far from clear what
>   the normal submodule traversal order is, because there is no
>   "natural" order to traverse.  Any of the combination of "top
>   down/bottom up" "width first/depth first" would make sense
>   depending on the application.  If you are doing "bottom up", for
>   example, please name it as such.
> 
> * The name "--append-superproject" sounds strange.  It sounds as if
>   you are appending the superproject to something else, but I
>   suspect that is not what is happening; instead perhaps you are
>   leaving the traversal of the superproject at the end, or
>   something?
> 
> Thanks.

Thank you for the feedback, I will apply it in regard to test fixes in the same commit.

Do you have any recommendation regarding names of these flags?

Do you have a preference for: —postorder-traversal or —bottom-up-traversal?

What about: —include-superpoject or —execute-in-superproject-last?

Re: [PATCH 5/5] doc: document reversive traversal and related modes

[William Hatfield]

> On Feb 1, 2026, at 4:03 AM, Jean-Noël AVILA <jn.avila@free.fr> wrote:
> 
> On Saturday, 31 January 2026 22:43:09 CET William Hatfield wrote:
>> Add documentation for the new --reverse-traversal, --append-superproject,
>> and --reversive flags to git-submodule.adoc. These flags enable post-order
>> traversal through nested submodule hierarchies, which is useful for
>> cleanup operations and dependency-ordered processing.
>> 
>> The flags only take effect when used with --recursive.
>> 
>> Signed-off-by: William Hatfield <whatfield.git@gmail.com>
> 
> Hello,
> 
> git-submodule is being transitioned to `synopsis` style of markup.
> See https://lore.kernel.org/git/
> 05e68e28257cd450463d253abe9b2995759bdc10.1769462744.git.gitgitgadget@gmail.com/
> 
> In the same move, there is some work on style consistency of the manual pages. 
> 
> Below are the remarks on what changed:
> 
>> ---
>> Documentation/git-submodule.adoc | 20 ++++++++++++++++++++
>> 1 file changed, 20 insertions(+)
>> 
>> diff --git a/Documentation/git-submodule.adoc b/Documentation/git-
> submodule.adoc
>> index 95beaee561..2be477952d 100644
>> --- a/Documentation/git-submodule.adoc
>> +++ b/Documentation/git-submodule.adoc
>> @@ -437,6 +437,26 @@ options carefully.
>> only in the submodules of the current repo, but also
>> in any nested submodules inside those submodules (and so on).
>> 
>> +--reverse-traversal::
> 
> Now, options in description lists are backticked:
> 
> `--reverse-traversal`::
> 
>> + This option is only valid for the foreach command and requires
>> + `--recursive`.  Process nested submodules in post-order (deepest
>> + first) rather than the default pre-order.  This is useful for
>> + cleanup operations where nested submodules must be processed
>> + before their parents.
> 
> Please start the description with the actual action of the option. Then, you 
> can add conditions, context, explanation:
> 
> Process nested [...]. This option is only valid [...]. This is useful [...]
> 
> Thanks

Thank you for the input. I will remedy the documentation as described.

Re: [PATCH 0/5] submodule: add 'reversive' traversal options to foreach

[Junio C Hamano]

William Hatfield <whatfield.git@gmail.com> writes:

> Do you have any recommendation regarding names of these flags?

Not really.  To be honest, I didn't even check to make sure what the
behaviour was that your "--reverse" was implementing ;-).

> Do you have a preference for: —postorder-traversal or —bottom-up-traversal?

If all three kinds of *order makes sense to the submodule traversal,
then --{pre,in,post}order would make sense.  In other words, does
there exist a good answer to this question: 

    What does "--inorder-traversal" would do and when would it be
    useful, as opposed to --preorder and --postorder?

Otherwise, the distinction between --bottom-up vs --top-down may be
sufficient to explain, and may explain the concept using more
familiar terms to us non-mathematics types.

> What about: —include-superpoject or —execute-in-superproject-last?

Depends on what you are trying to tell the command to do with these
options.

The former sounds as if you are saying "we usually do these things
only in submodules and never in superproject. But with this option I
am telling you to do the same in superproject after you are done
doing them in all the submoudles".

On the other hand, the latter sounds more like "do these things in
each and every repository (both submodules and the superproject),
but make sure the repository for superproject is handled after all
others."

Thanks.