scripts/git: Improve branch list comments

Hopefully, these explanations make it easier to get the next branch
transition right.

Part of 32772.

3 files changed, 18 insertions, 11 deletions

diff --git a/scripts/git/git-merge-forward.sh b/scripts/git/git-merge-forward.sh
index 8e61f6e644..bbc5047cb7 100755
--- a/scripts/git/git-merge-forward.sh
+++ b/scripts/git/git-merge-forward.sh
@@ -87,8 +87,10 @@ TOR_WKT_NAME=${TOR_WKT_NAME:-"tor-wkt"}
 # New arrays need to be in the WORKTREE= array else they aren't considered.
 #
 # Only used in test branch mode
-# There is no previous branch to merge forward, so the second and fifth items
-# must be blank ("")
+# We create a test branch for the earliest maint branch.
+# But it's the earliest maint branch, so we don't merge forward into it.
+# Since we don't merge forward into it, the second and fifth items must be
+# blank ("").
 MAINT_035_TB=( "maint-0.3.5" "" "$GIT_PATH/$TOR_WKT_NAME/maint-0.3.5" \
     "_035" "")
 # Used in maint/release merge and test branch modes
@@ -172,8 +174,8 @@ if [ -z "$TEST_BRANCH_PREFIX" ]; then
 
   # maint/release merge mode
   #
-  # List of all worktrees to work on. All defined above. Ordering is important.
-  # Always the maint-* branch BEFORE then the release-*.
+  # List of all worktrees to merge forward into. All defined above.
+  # Ordering is important. Always the maint-* branch BEFORE the release-*.
   WORKTREE=(
     # We don't merge forward into MAINT_035_TB[@], because it's the earliest
     # maint branch
@@ -193,7 +195,10 @@ if [ -z "$TEST_BRANCH_PREFIX" ]; then
 
 else
 
-  # Test branch mode: merge to maint only
+  # Test branch mode: base test branches on maint branches only
+  #
+  # List of all worktrees to create test branches from. All defined above.
+  # Ordering is important. All maint-* branches, including the earliest one.
   WORKTREE=(
     # We want a test branch based on the earliest maint branch
     MAINT_035_TB[@]
diff --git a/scripts/git/git-pull-all.sh b/scripts/git/git-pull-all.sh
index 6e02093adf..c8d115da01 100755
--- a/scripts/git/git-pull-all.sh
+++ b/scripts/git/git-pull-all.sh
@@ -91,8 +91,7 @@ EOF
 # Git worktrees to manage #
 ###########################
 
-# List of all worktrees to work on. All defined above. Ordering is important.
-# Always the maint-* branch first then the release-*.
+# List of all worktrees to pull. All defined above. Ordering is not important.
 WORKTREE=(
   MAINT_035[@]
   RELEASE_035[@]
diff --git a/scripts/git/git-push-all.sh b/scripts/git/git-push-all.sh
index 466b843f35..0abddc8023 100755
--- a/scripts/git/git-push-all.sh
+++ b/scripts/git/git-push-all.sh
@@ -97,9 +97,10 @@ PUSH_SAME=${TOR_PUSH_SAME:-0}
 # Argument processing #
 #######################
 
-# Controlled by the -t <test-branch-prefix> option. The test branch base
-# name option makes git-merge-forward.sh create new test branches:
-# <tbbn>_035, <tbbn>_040, ... , <tbbn>_master, and merge forward.
+# Controlled by the -t <test-branch-prefix> option. The test branch prefix
+# option makes git-merge-forward.sh create new test branches:
+# <tbp>_035, <tbp>_040, ... , <tbp>_master, and merge each branch forward into
+# the next one.
 TEST_BRANCH_PREFIX=
 
 while getopts ":hr:st:" opt; do
@@ -200,7 +201,7 @@ PUSH_BRANCHES=$(echo \
 
 if [ -z "$TEST_BRANCH_PREFIX" ]; then
 
-  # maint/release push mode
+  # maint/release push mode: push all branches.
   #
   # List of branches to push. Ordering is not important.
   PUSH_BRANCHES=$(echo \
@@ -212,6 +213,8 @@ if [ -z "$TEST_BRANCH_PREFIX" ]; then
     )
 else
 
+  # Test branch push mode: push test branches, based on each maint branch.
+  #
   # List of branches to push. Ordering is not important.
   PUSH_BRANCHES=" \
     ${TEST_BRANCH_PREFIX}_master \