bump-leg.py and setup-project.py: the git switch -c line says under it what to do where an earlier act left that branch, so already exists is no dead end (#607's sentence, in the two tools it left)

scripts/bump-leg.py

@@ -1146,12 +1146,31 @@ def _switch_command(root: Path, role: str, commit: str) -> str:
     root, which always holds a backslash, prints in single quotes, as
     `shlex` spells it. They are lines for a POSIX shell (Git Bash, or WSL2
     on Windows), as `update-shape.py`'s are, and README's "Windows,
-    natively" says so.
+    natively" says so. Each of the three is followed by `BRANCH_LEFT`, for a
+    root that has the branch already (#647).
     """
     return shlex.join(["git", "-C", str(root), "switch", "-c",
                        f"bump/{role}-{commit[:12]}"])
 
 
+#: What every place that names `_switch_command` says under it (#647): where
+#: an earlier act left that branch, `switch -c` fails `fatal: a branch named
+#: '<branch>' already exists` (exit 128), and nothing said what to do next.
+#: Another name comes first, because a new branch starts where the project
+#: stands now; going back to the old branch is right only where it holds work
+#: not merged yet, and `git switch` keeps its commits. IN WORDS, NOT A SECOND
+#: COMMAND, as `family.py` and the holder's `validate-family.py` say it: no
+#: line of ours changes, so none needs quoting, and the three tools follow one
+#: rule. THE SAME SENTENCE as their `BRANCH_LEFT` (#607), word for word, with
+#: "the project" where they say "the holder".
+BRANCH_LEFT = ("If `git switch -c` says that branch already exists, an "
+               "earlier act left it: give the branch another name, which "
+               "starts it where the project stands, or, only if that branch "
+               "holds work not merged yet, the same command with `switch` "
+               "in place of `switch -c` goes back to it and keeps every "
+               "commit on it.")
+
+
 def _branch_to_bump_from(root: Path, project: "Project", role: str,
                          commit: str, *, dry_run: bool = False) -> str:
     """The branch on which the bump commits, refused if there is none or
@@ -1163,7 +1182,8 @@ def _branch_to_bump_from(root: Path, project: "Project", role: str,
     commit, so on the tracking branch it is let through and ends by naming
     the branch the real run needs (#477); a root on no branch at all is
     refused either way. Both refusals name that branch's `switch -c`
-    through `_switch_command`, quoted (#532).
+    through `_switch_command`, quoted (#532), and end with `BRANCH_LEFT`, the
+    sentence for a root that has that branch already (#647).
     """
     branch = current_branch(root)
     if branch is None:
@@ -1172,7 +1192,7 @@ def _branch_to_bump_from(root: Path, project: "Project", role: str,
             f"{root} is not on a branch, so there is no branch to push and "
             "open a pull request from",
             f"Remediation: `{_switch_command(root, role, commit)}` and "
-            "re-run.")
+            f"re-run.\n{BRANCH_LEFT}")
     if branch == project.tracking and not dry_run:
         raise Refusal(
             "bump-leg-on-tracking-branch",
@@ -1181,7 +1201,8 @@ def _branch_to_bump_from(root: Path, project: "Project", role: str,
             "Remediation: these organisations are pull-request only, so this "
             "will not make a commit whose only next step is a push to the "
             "default branch. Run:\n    "
-            f"{_switch_command(root, role, commit)}\nand re-run.")
+            f"{_switch_command(root, role, commit)}\nand re-run.\n"
+            f"{BRANCH_LEFT}")
     return branch
 
 
@@ -1670,11 +1691,13 @@ def cmd_bump(args) -> int:
               "untouched.")
         if branch == project.tracking:
             # LAST, after everything a dry run on a branch prints, so that
-            # line is the whole of the difference between the two (#477).
-            # The command is quoted, so a root under `My Projects/` pastes.
+            # line and the sentence under it are the whole of the difference
+            # between the two (#477, #647). The command is quoted, so a root
+            # under `My Projects/` pastes.
             print(f"\nthe real run needs a branch: {root} is on {branch!r}, "
                   "the tracking branch. Create one first with: "
                   + _switch_command(root, role, asked))
+            print(BRANCH_LEFT)
         return 0
 
     # ---- the rewrite and the commit, remembered byte for byte so a failure

setup-project.py

@@ -2515,6 +2515,25 @@ def shell_word(value, posix: bool = False) -> str:
     return "'" + text.replace("'", "'\\''") + "'"
 
 
+#: What the `switch -c` line of the family block says under it (#647): where
+#: an earlier try left that branch in the holder, `switch -c` fails `fatal: a
+#: branch named '<branch>' already exists` (exit 128). Another name comes
+#: first, because a new branch starts where the holder stands now; going back
+#: is right only where the old branch holds work not merged yet. IN WORDS, NOT
+#: A SECOND COMMAND, so no line changes and none needs quoting. THE SAME
+#: SENTENCE as `scripts/family.py`'s and the holder's `validate-family.py`'s
+#: `BRANCH_LEFT` (#607), word for word: this file carries its own copy, as it
+#: does of `shell_word`, because it runs before any checkout of the standard
+#: exists, and `tests/test_branch_left_bump_leg_setup.py` holds them to one
+#: answer.
+BRANCH_LEFT = ("If `git switch -c` says that branch already exists, an "
+               "earlier act left it: give the branch another name, which "
+               "starts it where the holder stands, or, only if that branch "
+               "holds work not merged yet, the same command with `switch` "
+               "in place of `switch -c` goes back to it and keeps every "
+               "commit on it.")
+
+
 def family_next_command(project: str, org: str, landing: Landing) -> None:
     """The LAST line of the next commands: who records the membership.
 
@@ -2533,12 +2552,15 @@ def family_next_command(project: str, org: str, landing: Landing) -> None:
     A BRANCH FIRST, AND EVERY PATH ONE WORD (#487, #486). `add` refuses to
     commit onto the holder's tracking branch, so the `git switch -c` that
     makes the branch it suggests comes before it; and a holder under a
-    folder with a space in it must reach `--family-root` whole.
+    folder with a space in it must reach `--family-root` whole. Under the
+    `switch -c`, one comment line says what to do where the holder has that
+    branch already (`BRANCH_LEFT`, #647).
     """
     holder = shell_word(landing.holder)
     say("    git -C %s switch -c family/add-%s" % (holder, project.lower()))
     say("                           # a branch first: `add` refuses the")
     say("                           #   holder's tracking branch")
+    say("                           # " + BRANCH_LEFT)
     say("    %s scripts/family.py add --family-root %s --member %s"
         % (PYTHON_CMD, holder, shell_word("%s/%s" % (org, project))))
     say("                           # from a checkout of openRepoShape. The")