Skip rebase in traverse for branches behind remote

Author: PawelLipski

RELEASE_NOTES.md

@@ -2,6 +2,8 @@
 
 ## New in git-machete 3.39.3
 
+- changed: when a branch is behind remote (needs a pull), `git machete traverse` now skips rebase,
+  just as it did already when branch is diverged from & older than remote (suggested by @lsierant)
 - fixed: when `git machete traverse` failed on a rebase within a worktree,
   in certain cases the warning message about changed directory didn't show up (reported by @lsierant)
 

docs/man/git-machete.1

@@ -2085,9 +2085,11 @@ git machete t[raverse] [\-F|\-\-fetch] [\-l|\-\-list\-commits] [\-M|\-\-merge]
 .sp
 Walk the branches in the order as they occur in branch layout file.
 By default, \fBtraverse\fP starts from the current branch.
-This behavior can, however, be customized using options: \fB\-\-start\-from=\fP, \fB\-\-whole\fP or \fB\-w\fP, \fB\-W\fP\&.
+This behavior can, however, be customized using options: \fB\-\-start\-from=...\fP, \fB\-\-whole\fP (\fB\-w\fP) or \fB\-W\fP\&.
 .sp
-For each branch, the command:
+For each branch, the command performs the following actions:
+.sp
+\fBSync to parent\fP
 .INDENT 0.0
 .IP \(bu 2
 detects if the branch is merged (gray edge) to its parent (aka upstream):
@@ -2102,6 +2104,10 @@ otherwise, if the branch has a red or yellow edge to its parent/upstream (see he
 asks the user whether to \fBrebase\fP (default) or merge (if \fB\-\-merge\fP passed) the branch onto into its upstream branch
 \-\-\- equivalent to \fBgit machete update\fP;
 .UNINDENT
+.UNINDENT
+.sp
+\fBSync to remote\fP
+.INDENT 0.0
 .IP \(bu 2
 if the branch is not tracked on a remote, is ahead of its remote counterpart, or diverged from the counterpart &
 has newer head commit than the counterpart:
@@ -2114,13 +2120,19 @@ otherwise, if the branch diverged from the remote counterpart & has older head c
 .INDENT 2.0
 .IP \(bu 2
 asks the user whether to \fBreset\fP (\fBgit reset \-\-keep\fP) the branch to its remote counterpart
+\-\-\- note that rebase/merge isn\(aqt suggested in that case;
 .UNINDENT
 .IP \(bu 2
 otherwise, if the branch is behind its remote counterpart:
 .INDENT 2.0
 .IP \(bu 2
-asks the user whether to \fBpull\fP the branch;
+asks the user whether to \fBpull\fP the branch
+\-\-\- note that rebase/merge isn\(aqt suggested in that case;
+.UNINDENT
 .UNINDENT
+.sp
+\fBSync to GitHub/GitLab\fP
+.INDENT 0.0
 .IP \(bu 2
 if \fB\-H\fP/\fB\-\-sync\-github\-prs\fP or \fB\-L\fP/\fB\-\-sync\-gitlab\-mrs\fP option is present:
 .INDENT 2.0
@@ -2131,18 +2143,18 @@ asks the user whether to \fBretarget\fP the PR/MR if it exists for the given bra
 and its base/target branch in GitHub/GitLab is different than the upstream in machete file
 (just as \fBgit machete github retarget\-pr\fP and \fBgit machete gitlab retarget\-mr\fP would do);
 .UNINDENT
+.UNINDENT
+.sp
+\fBStatus\fP
+.INDENT 0.0
 .IP \(bu 2
-and finally, if any of the above operations has been successfully completed:
+finally, if any of the above operations has been successfully completed:
 .INDENT 2.0
 .IP \(bu 2
 prints the updated \fBstatus\fP\&.
 .UNINDENT
 .UNINDENT
 .sp
-By default \fBtraverse\fP asks if the branch should be pushed. This behavior can, however, be changed with the \fBmachete.traverse.push\fP configuration key.
-It can also be customized using options: \fB\-\-[no\-]push\fP or \fB\-\-[no\-]push\-untracked\fP \-\-\- the order of the flags defines their precedence over each other
-(the one on the right overriding the ones on the left). More on them in the \fBOptions\fP section below.
-.sp
 If the traverse flow is stopped (typically due to merge/rebase conflicts), just run \fBgit machete traverse\fP after the merge/rebase is finished.
 It will pick up the walk from the current branch.
 Unlike with \fBgit rebase\fP or \fBgit cherry\-pick\fP, there is no special \fB\-\-continue\fP flag, as \fBtraverse\fP is stateless.

docs/source/cli/traverse.rst

@@ -26,9 +26,11 @@ traverse
 
 Walk the branches in the order as they occur in branch layout file.
 By default, ``traverse`` starts from the current branch.
-This behavior can, however, be customized using options: ``--start-from=``, ``--whole`` or ``-w``, ``-W``.
+This behavior can, however, be customized using options: ``--start-from=...``, ``--whole`` (``-w``) or ``-W``.
 
-For each branch, the command:
+For each branch, the command performs the following actions:
+
+**Sync to parent**
 
 * detects if the branch is merged (:gray:`gray` edge) to its parent (aka upstream):
 
@@ -39,6 +41,8 @@ For each branch, the command:
   - asks the user whether to **rebase** (default) or merge (if ``--merge`` passed) the branch onto into its upstream branch
     --- equivalent to ``git machete update``;
 
+**Sync to remote**
+
 * if the branch is not tracked on a remote, is ahead of its remote counterpart, or diverged from the counterpart &
   has newer head commit than the counterpart:
 
@@ -47,10 +51,14 @@ For each branch, the command:
 * otherwise, if the branch diverged from the remote counterpart & has older head commit than the counterpart:
 
   - asks the user whether to **reset** (``git reset --keep``) the branch to its remote counterpart
+    --- note that rebase/merge isn't suggested in that case;
 
 * otherwise, if the branch is behind its remote counterpart:
 
-  - asks the user whether to **pull** the branch;
+  - asks the user whether to **pull** the branch
+    --- note that rebase/merge isn't suggested in that case;
+
+**Sync to GitHub/GitLab**
 
 * if ``-H``/``--sync-github-prs`` or ``-L``/``--sync-gitlab-mrs`` option is present:
 
@@ -60,13 +68,11 @@ For each branch, the command:
     and its base/target branch in GitHub/GitLab is different than the upstream in machete file
     (just as ``git machete github retarget-pr`` and ``git machete gitlab retarget-mr`` would do);
 
-* and finally, if any of the above operations has been successfully completed:
+**Status**
 
-  - prints the updated ``status``.
+* finally, if any of the above operations has been successfully completed:
 
-By default ``traverse`` asks if the branch should be pushed. This behavior can, however, be changed with the ``machete.traverse.push`` configuration key.
-It can also be customized using options: ``--[no-]push`` or ``--[no-]push-untracked`` --- the order of the flags defines their precedence over each other
-(the one on the right overriding the ones on the left). More on them in the **Options** section below.
+  - prints the updated ``status``.
 
 If the traverse flow is stopped (typically due to merge/rebase conflicts), just run ``git machete traverse`` after the merge/rebase is finished.
 It will pick up the walk from the current branch.

git_machete/client/traverse.py

@@ -223,16 +223,16 @@ def traverse(
 
                 use_merge = opt_merge or (branch in self.annotations and self.annotations[branch].qualifiers.update_with_merge)
 
+                skipping_parent_sync = False
+
                 if needs_slide_out:
                     # Avoid unnecessary fork point check if we already know that the
                     # branch qualifies for slide out;
                     # neither rebase nor merge will be suggested in such case anyway.
                     needs_parent_sync: bool = False
-                elif s == SyncToRemoteStatus.DIVERGED_FROM_AND_OLDER_THAN_REMOTE:
-                    # Avoid unnecessary fork point check if we already know that the
-                    # branch qualifies for resetting to remote counterpart;
-                    # neither rebase nor merge will be suggested in such case anyway.
+                elif s in (SyncToRemoteStatus.BEHIND_REMOTE, SyncToRemoteStatus.DIVERGED_FROM_AND_OLDER_THAN_REMOTE):
                     needs_parent_sync = False
+                    skipping_parent_sync = bool(upstream)
                 elif use_merge:
                     needs_parent_sync = bool(
                         upstream and not self._git.is_ancestor_or_equal(upstream.full_name(), branch.full_name()))
@@ -369,6 +369,15 @@ def traverse(
                     elif ans in ('q', 'quit'):
                         return
 
+                if skipping_parent_sync:
+                    assert upstream is not None
+                    self._print_new_line(False)
+                    if s == SyncToRemoteStatus.BEHIND_REMOTE:
+                        reason = "behind its remote counterpart"
+                    else:
+                        reason = "diverged from (and has older commits than) its remote counterpart"
+                    print(f"Skipping sync of {bold(branch)} with {bold(upstream)}; {bold(branch)} is {reason}")
+
                 if needs_retarget_pr:
                     any_action_suggested = True
                     assert pr is not None

git_machete/generated_docs.py

@@ -1447,9 +1447,11 @@
 
         Walk the branches in the order as they occur in branch layout file.
         By default, `traverse` starts from the current branch.
-        This behavior can, however, be customized using options: `--start-from=`, `--whole` or `-w`, `-W`.
+        This behavior can, however, be customized using options: `--start-from=...`, `--whole` (`-w`) or `-W`.
 
-        For each branch, the command:
+        For each branch, the command performs the following actions:
+
+        <b>Sync to parent</b>
 
            * detects if the branch is merged (<gray>gray</gray> edge) to its parent (aka upstream):
 
@@ -1460,6 +1462,8 @@
              - asks the user whether to <b>rebase</b> (default) or merge (if `--merge` passed) the branch onto into its upstream branch
               — equivalent to `git machete update`;
 
+        <b>Sync to remote</b>
+
            * if the branch is not tracked on a remote, is ahead of its remote counterpart, or diverged from the counterpart &
              has newer head commit than the counterpart:
 
@@ -1468,10 +1472,14 @@
            * otherwise, if the branch diverged from the remote counterpart & has older head commit than the counterpart:
 
              - asks the user whether to <b>reset</b> (`git reset --keep`) the branch to its remote counterpart
+              — note that rebase/merge isn't suggested in that case;
 
            * otherwise, if the branch is behind its remote counterpart:
 
-             - asks the user whether to <b>pull</b> the branch;
+             - asks the user whether to <b>pull</b> the branch
+              — note that rebase/merge isn't suggested in that case;
+
+        <b>Sync to GitHub/GitLab</b>
 
            * if `-H`/`--sync-github-prs` or `-L`/`--sync-gitlab-mrs` option is present:
 
@@ -1481,13 +1489,11 @@
               and its base/target branch in GitHub/GitLab is different than the upstream in machete file
               (just as `git machete github retarget-pr` and `git machete gitlab retarget-mr` would do);
 
-           * and finally, if any of the above operations has been successfully completed:
+        <b>Status</b>
 
-             - prints the updated `status`.
+           * finally, if any of the above operations has been successfully completed:
 
-        By default `traverse` asks if the branch should be pushed. This behavior can, however, be changed with the `machete.traverse.push` configuration key.
-        It can also be customized using options: `--[no-]push` or `--[no-]push-untracked` — the order of the flags defines their precedence over each other
-        (the one on the right overriding the ones on the left). More on them in the <b>Options</b> section below.
+             - prints the updated `status`.
 
         If the traverse flow is stopped (typically due to merge/rebase conflicts), just run `git machete traverse` after the merge/rebase is finished.
         It will pick up the walk from the current branch.

tests/test_traverse.py

@@ -1,3 +1,4 @@
+# flake8: noqa: E501
 import os
 
 import pytest
@@ -1070,6 +1071,8 @@ def test_traverse_start_from_branch_names(self) -> None:
                 |
                 o-ignore-trailing * (diverged from & older than origin)
 
+            Skipping sync of ignore-trailing with hotfix/add-trigger; ignore-trailing is diverged from (and has older commits than) its remote counterpart
+
             Branch ignore-trailing diverged from (and has older commits than) its remote counterpart origin/ignore-trailing.
             Resetting branch ignore-trailing to the commit pointed by origin/ignore-trailing...
 
@@ -1230,6 +1233,8 @@ def test_traverse_start_from_case_insensitive_special_values(self) -> None:
                 |
                 o-ignore-trailing * (diverged from & older than origin)
 
+            Skipping sync of ignore-trailing with hotfix/add-trigger; ignore-trailing is diverged from (and has older commits than) its remote counterpart
+
             Branch ignore-trailing diverged from (and has older commits than) its remote counterpart origin/ignore-trailing.
             Resetting branch ignore-trailing to the commit pointed by origin/ignore-trailing...
             Checking out call-ws... OK
@@ -1332,6 +1337,8 @@ def test_traverse_branch_priority_over_special_values(self) -> None:
                 |
                 o-ignore-trailing * (diverged from & older than origin)
 
+            Skipping sync of ignore-trailing with hotfix/add-trigger; ignore-trailing is diverged from (and has older commits than) its remote counterpart
+
             Branch ignore-trailing diverged from (and has older commits than) its remote counterpart origin/ignore-trailing.
             Resetting branch ignore-trailing to the commit pointed by origin/ignore-trailing...
 
@@ -1948,3 +1955,67 @@ def test_traverse_rebase_conflict(self) -> None:
             Rebasing feature onto master...
             """
         )
+
+    def test_traverse_behind_remote_with_red_edge(self) -> None:
+        create_repo_with_remote()
+        new_branch("master")
+        commit()
+        new_branch("feature")
+        commit()
+        commit()
+        push()
+        reset_to("HEAD~")
+        check_out("master")
+        commit()
+        push()
+        check_out("feature")
+
+        rewrite_branch_layout_file("master\n\tfeature")
+
+        assert_success(
+            ["traverse", "-y"],
+            """
+            Skipping sync of feature with master; feature is behind its remote counterpart
+
+            Branch feature is behind its remote counterpart origin/feature.
+            Pulling feature (fast-forward only) from origin...
+
+              master
+              |
+              x-feature *
+
+            Reached branch feature which has no successor; nothing left to update
+            """
+        )
+
+    def test_traverse_diverged_from_and_older_with_red_edge(self) -> None:
+        create_repo_with_remote()
+        new_branch("master")
+        commit()
+        new_branch("feature")
+        commit()
+        push()
+        with fixed_author_and_committer_date_in_past():
+            amend_commit()
+        check_out("master")
+        commit()
+        push()
+        check_out("feature")
+
+        rewrite_branch_layout_file("master\n\tfeature")
+
+        assert_success(
+            ["traverse", "-y"],
+            """
+            Skipping sync of feature with master; feature is diverged from (and has older commits than) its remote counterpart
+
+            Branch feature diverged from (and has older commits than) its remote counterpart origin/feature.
+            Resetting branch feature to the commit pointed by origin/feature...
+
+              master
+              |
+              x-feature *
+
+            Reached branch feature which has no successor; nothing left to update
+            """
+        )