status: clarify how status.compareBranches deduplicates

HaraldNordgren · gitster · commit 68791d7506aa · 2026-03-04T10:13:33.000-08:00
The order of output when multiple branches are specified on the
configuration variable was not clearly spelled out in the
documentation.

Add a paragraph to describe the order and also how the branches are
deduplicated.  Update t6040 with additional tests to illustrate how
multiple branches are shown and deduplicated.

Signed-off-by: Harald Nordgren &lt;haraldnordgren@gmail.com&gt;
[jc: made a whole replacement into incremental; wrote log message.]
Signed-off-by: Junio C Hamano &lt;gitster@pobox.com&gt;
diff --git a/Documentation/config/status.adoc b/Documentation/config/status.adoc
@@ -26,6 +26,12 @@ status.compareBranches::
 If not set, the default behavior is equivalent to `@{upstream}`, which
 compares against the configured upstream tracking branch.
 +
+The entries are shown in the order they appear in the configuration.
+Duplicate entries that resolve to the same ref are suppressed after
+their first occurrence, so `@{push} @{upstream} @{push}` shows at
+most two comparisons.  When `@{upstream}` and `@{push}` resolve to
+the same remote-tracking branch, only one comparison is shown.
++
 Example:
 +
 ----
diff --git a/t/t6040-tracking-info.sh b/t/t6040-tracking-info.sh
@@ -293,11 +293,8 @@ test_expect_success '--set-upstream-to @{-1}' '
 '
 
 test_expect_success 'status tracking origin/main shows only main' '
-	(
-		cd test &&
-		git checkout b4 &&
-		git status >../actual
-	) &&
+	git -C test checkout b4 &&
+	git -C test status >actual &&
 	cat >expect <<-EOF &&
 	On branch b4
 	Your branch is ahead of ${SQ}origin/main${SQ} by 2 commits.
@@ -309,11 +306,8 @@ test_expect_success 'status tracking origin/main shows only main' '
 '
 
 test_expect_success 'status --no-ahead-behind tracking origin/main shows only main' '
-	(
-		cd test &&
-		git checkout b4 &&
-		git status --no-ahead-behind >../actual
-	) &&
+	git -C test checkout b4 &&
+	git -C test status --no-ahead-behind >actual &&
 	cat >expect <<-EOF &&
 	On branch b4
 	Your branch and ${SQ}origin/main${SQ} refer to different commits.
@@ -324,7 +318,7 @@ test_expect_success 'status --no-ahead-behind tracking origin/main shows only ma
 	test_cmp expect actual
 '
 
-test_expect_success 'status.compareBranches from upstream has no duplicates' '
+test_expect_success 'status.compareBranches deduplicates when upstream and push are the same' '
 	test_config -C test status.compareBranches "@{upstream} @{push}" &&
 	git -C test checkout main &&
 	git -C test status >actual &&
@@ -337,18 +331,48 @@ test_expect_success 'status.compareBranches from upstream has no duplicates' '
 	test_cmp expect actual
 '
 
-test_expect_success 'status.compareBranches shows ahead of both upstream and push branch' '
+test_expect_success 'status.compareBranches with only upstream shows only upstream' '
+	test_config -C test status.compareBranches "@{upstream}" &&
+	git -C test checkout main &&
+	git -C test status >actual &&
+	cat >expect <<-EOF &&
+	On branch main
+	Your branch is up to date with ${SQ}origin/main${SQ}.
+
+	nothing to commit, working tree clean
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'status.compareBranches with only push shows only push' '
 	test_config -C test push.default current &&
-	test_config -C test status.compareBranches "@{upstream} @{push}" &&
+	test_config -C test status.compareBranches "@{push}" &&
 	git -C test checkout -b feature2 origin/main &&
 	git -C test push origin HEAD &&
 	(cd test && advance work) &&
 	git -C test status >actual &&
 	cat >expect <<-EOF &&
 	On branch feature2
+	Your branch is ahead of ${SQ}origin/feature2${SQ} by 1 commit.
+	  (use "git push" to publish your local commits)
+
+	nothing to commit, working tree clean
+	EOF
+	test_cmp expect actual
+'
+
+test_expect_success 'status.compareBranches shows ahead of both upstream and push branch' '
+	test_config -C test push.default current &&
+	test_config -C test status.compareBranches "@{upstream} @{push}" &&
+	git -C test checkout -b feature3 origin/main &&
+	git -C test push origin HEAD &&
+	(cd test && advance work) &&
+	git -C test status >actual &&
+	cat >expect <<-EOF &&
+	On branch feature3
 	Your branch is ahead of ${SQ}origin/main${SQ} by 1 commit.
 
-	Your branch is ahead of ${SQ}origin/feature2${SQ} by 1 commit.
+	Your branch is ahead of ${SQ}origin/feature3${SQ} by 1 commit.
 	  (use "git push" to publish your local commits)
 
 	nothing to commit, working tree clean
@@ -359,11 +383,11 @@ test_expect_success 'status.compareBranches shows ahead of both upstream and pus
 test_expect_success 'checkout with status.compareBranches shows both branches' '
 	test_config -C test push.default current &&
 	test_config -C test status.compareBranches "@{upstream} @{push}" &&
-	git -C test checkout feature2 >actual &&
+	git -C test checkout feature3 >actual &&
 	cat >expect <<-EOF &&
 	Your branch is ahead of ${SQ}origin/main${SQ} by 1 commit.
 
-	Your branch is ahead of ${SQ}origin/feature2${SQ} by 1 commit.
+	Your branch is ahead of ${SQ}origin/feature3${SQ} by 1 commit.
 	  (use "git push" to publish your local commits)
 	EOF
 	test_cmp expect actual
@@ -469,21 +493,41 @@ test_expect_success 'status.compareBranches supports ordered upstream/push entri
 	test_cmp expect actual
 '
 
+test_expect_success 'status.compareBranches deduplicates repeated specifiers' '
+	test_config -C test push.default current &&
+	test_config -C test remote.pushDefault origin &&
+	test_config -C test status.compareBranches "@{push} @{upstream} @{push}" &&
+	git -C test checkout -b feature7 upstream/main &&
+	git -C test push origin &&
+	(cd test && advance work) &&
+	git -C test status >actual &&
+	cat >expect <<-EOF &&
+	On branch feature7
+	Your branch is ahead of ${SQ}origin/feature7${SQ} by 1 commit.
+	  (use "git push" to publish your local commits)
+
+	Your branch is ahead of ${SQ}upstream/main${SQ} by 1 commit.
+
+	nothing to commit, working tree clean
+	EOF
+	test_cmp expect actual
+'
+
 test_expect_success 'status.compareBranches with diverged push branch' '
 	test_config -C test push.default current &&
 	test_config -C test remote.pushDefault origin &&
 	test_config -C test status.compareBranches "@{upstream} @{push}" &&
-	git -C test checkout -b feature7 upstream/main &&
-	(cd test && advance work71) &&
+	git -C test checkout -b feature8 upstream/main &&
+	(cd test && advance work81) &&
 	git -C test push origin &&
 	git -C test reset --hard upstream/main &&
-	(cd test && advance work72) &&
+	(cd test && advance work82) &&
 	git -C test status >actual &&
 	cat >expect <<-EOF &&
-	On branch feature7
+	On branch feature8
 	Your branch is ahead of ${SQ}upstream/main${SQ} by 1 commit.
 
-	Your branch and ${SQ}origin/feature7${SQ} have diverged,
+	Your branch and ${SQ}origin/feature8${SQ} have diverged,
 	and have 1 and 1 different commits each, respectively.
 
 	nothing to commit, working tree clean
@@ -495,14 +539,14 @@ test_expect_success 'status.compareBranches shows up to date branches' '
 	test_config -C test push.default current &&
 	test_config -C test remote.pushDefault origin &&
 	test_config -C test status.compareBranches "@{upstream} @{push}" &&
-	git -C test checkout -b feature8 upstream/main &&
+	git -C test checkout -b feature9 upstream/main &&
 	git -C test push origin &&
 	git -C test status >actual &&
 	cat >expect <<-EOF &&
-	On branch feature8
+	On branch feature9
 	Your branch is up to date with ${SQ}upstream/main${SQ}.
 
-	Your branch is up to date with ${SQ}origin/feature8${SQ}.
+	Your branch is up to date with ${SQ}origin/feature9${SQ}.
 
 	nothing to commit, working tree clean
 	EOF
@@ -513,14 +557,14 @@ test_expect_success 'status --no-ahead-behind with status.compareBranches up to
 	test_config -C test push.default current &&
 	test_config -C test remote.pushDefault origin &&
 	test_config -C test status.compareBranches "@{upstream} @{push}" &&
-	git -C test checkout feature8 >actual &&
+	git -C test checkout feature9 >actual &&
 	git -C test push origin &&
 	git -C test status --no-ahead-behind >actual &&
 	cat >expect <<-EOF &&
-	On branch feature8
+	On branch feature9
 	Your branch is up to date with ${SQ}upstream/main${SQ}.
 
-	Your branch is up to date with ${SQ}origin/feature8${SQ}.
+	Your branch is up to date with ${SQ}origin/feature9${SQ}.
 
 	nothing to commit, working tree clean
 	EOF
@@ -531,11 +575,11 @@ test_expect_success 'checkout with status.compareBranches shows up to date' '
 	test_config -C test push.default current &&
 	test_config -C test remote.pushDefault origin &&
 	test_config -C test status.compareBranches "@{upstream} @{push}" &&
-	git -C test checkout feature8 >actual &&
+	git -C test checkout feature9 >actual &&
 	cat >expect <<-EOF &&
 	Your branch is up to date with ${SQ}upstream/main${SQ}.
 
-	Your branch is up to date with ${SQ}origin/feature8${SQ}.
+	Your branch is up to date with ${SQ}origin/feature9${SQ}.
 	EOF
 	test_cmp expect actual
 '
@@ -547,31 +591,31 @@ test_expect_success 'status.compareBranches with upstream behind and push up to
 	git -C test checkout -b ahead upstream/main &&
 	(cd test && advance work) &&
 	git -C test push upstream HEAD &&
-	git -C test checkout -b feature9 upstream/main &&
+	git -C test checkout -b feature10 upstream/main &&
 	git -C test push origin &&
 	git -C test branch --set-upstream-to upstream/ahead &&
 	git -C test status >actual &&
 	cat >expect <<-EOF &&
-	On branch feature9
+	On branch feature10
 	Your branch is behind ${SQ}upstream/ahead${SQ} by 1 commit, and can be fast-forwarded.
 	  (use "git pull" to update your local branch)
 
-	Your branch is up to date with ${SQ}origin/feature9${SQ}.
+	Your branch is up to date with ${SQ}origin/feature10${SQ}.
 
 	nothing to commit, working tree clean
 	EOF
 	test_cmp expect actual
 '
 
 test_expect_success 'status.compareBranches with remapped push refspec' '
-	test_config -C test remote.origin.push refs/heads/feature10:refs/heads/remapped &&
+	test_config -C test remote.origin.push refs/heads/feature11:refs/heads/remapped &&
 	test_config -C test status.compareBranches "@{upstream} @{push}" &&
-	git -C test checkout -b feature10 origin/main &&
+	git -C test checkout -b feature11 origin/main &&
 	git -C test push &&
 	(cd test && advance work) &&
 	git -C test status >actual &&
 	cat >expect <<-EOF &&
-	On branch feature10
+	On branch feature11
 	Your branch is ahead of ${SQ}origin/main${SQ} by 1 commit.
 
 	Your branch is ahead of ${SQ}origin/remapped${SQ} by 1 commit.
@@ -584,14 +628,14 @@ test_expect_success 'status.compareBranches with remapped push refspec' '
 
 test_expect_success 'status.compareBranches with remapped push and upstream remote' '
 	test_config -C test remote.pushDefault origin &&
-	test_config -C test remote.origin.push refs/heads/feature11:refs/heads/remapped &&
+	test_config -C test remote.origin.push refs/heads/feature12:refs/heads/remapped &&
 	test_config -C test status.compareBranches "@{upstream} @{push}" &&
-	git -C test checkout -b feature11 upstream/main &&
+	git -C test checkout -b feature12 upstream/main &&
 	git -C test push origin &&
 	(cd test && advance work) &&
 	git -C test status >actual &&
 	cat >expect <<-EOF &&
-	On branch feature11
+	On branch feature12
 	Your branch is ahead of ${SQ}upstream/main${SQ} by 1 commit.
 
 	Your branch is ahead of ${SQ}origin/remapped${SQ} by 1 commit.

Original file line number	Diff line number	Diff line change
`@@ -26,6 +26,12 @@ status.compareBranches::`
`26`	`26`	If not set, the default behavior is equivalent to `@{upstream}`, which
`27`	`27`	`compares against the configured upstream tracking branch.`
`28`	`28`	`+`
	`29`	`+The entries are shown in the order they appear in the configuration.`
	`30`	`+Duplicate entries that resolve to the same ref are suppressed after`
	`31`	+their first occurrence, so `@{push} @{upstream} @{push}` shows at
	`32`	+most two comparisons. When `@{upstream}` and `@{push}` resolve to
	`33`	`+the same remote-tracking branch, only one comparison is shown.`
	`34`	`++`
`29`	`35`	`Example:`
`30`	`36`	`+`
`31`	`37`	`----`