Detect and fix circular imports

PawelLipski · PawelLipski · commit fa153b2e82c3 · 2026-03-30T17:24:08.000+02:00
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -71,7 +71,7 @@ jobs:
           command: ci/checks/run-all-checks.sh
       - run:
           name: Check code style
-          command: tox -e isort-check,flake8-check,typos-check,vulture-check
+          command: tox -e isort-check,flake8-check,typos-check,vulture-check,cyclic-import-check
       - run:
           name: Verify docs
           command: tox -e py-docs-check,sphinx-man-check,sphinx-html
@@ -298,7 +298,7 @@ only_special_branches: &only_special_branches
   filters:
     branches:
       only:
-        - "/.*(aur|ci|dependabot.pip|deploy|dry.run|hotfix|macos|nix|publish|release|windows).*/"
+        - "/.*(aur|ci[/-]|dependabot.pip|deploy|dry.run|hotfix|macos|nix|publish|release|windows).*/"
         - "develop"
         - "master"
 
diff --git a/docs/man/git-machete.1 b/docs/man/git-machete.1
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "GIT-MACHETE" "1" "Mar 12, 2026" "" "git-machete"
+.TH "GIT-MACHETE" "1" "Mar 30, 2026" "" "git-machete"
 .SH NAME
 git-machete \- git-machete 3.39.3
 .sp
diff --git a/git_machete/cli.py b/git_machete/cli.py
@@ -31,11 +31,11 @@
 from git_machete.github import GITHUB_CLIENT_SPEC
 from git_machete.gitlab import GITLAB_CLIENT_SPEC
 
-from .exceptions import (ExitCode, InteractionStopped, MacheteException,
-                         UnderlyingGitException, UnexpectedMacheteException)
 from .generated_docs import long_docs, short_docs
 from .git_operations import AnyRevision, GitContext, LocalBranchShortName
-from .utils import bold, fmt, green_ok, print_no_newline, underline, warn
+from .utils import (ExitCode, InteractionStopped, MacheteException,
+                    UnderlyingGitException, UnexpectedMacheteException, bold,
+                    fmt, green_ok, print_no_newline, underline, warn)
 
 T = TypeVar('T')
 
diff --git a/git_machete/client/advance.py b/git_machete/client/advance.py
@@ -1,9 +1,9 @@
 from git_machete.client.base import MacheteClient
 from git_machete.config import SquashMergeDetection
-from git_machete.exceptions import MacheteException
 from git_machete.git_operations import (GitContext, LocalBranchShortName,
                                         SyncToRemoteStatus)
-from git_machete.utils import bold, flat_map, get_pretty_choices, warn
+from git_machete.utils import (MacheteException, bold, flat_map,
+                               get_pretty_choices, warn)
 
 
 class AdvanceMacheteClient(MacheteClient):
diff --git a/git_machete/client/base.py b/git_machete/client/base.py
@@ -13,17 +13,17 @@
 from git_machete.config import MacheteConfig, SquashMergeDetection
 from git_machete.constants import (INITIAL_COMMIT_COUNT_FOR_LOG,
                                    TOTAL_COMMIT_COUNT_FOR_LOG)
-from git_machete.exceptions import (InteractionStopped, MacheteException,
-                                    UnexpectedMacheteException)
 from git_machete.git_operations import (HEAD, AnyBranchName, AnyRevision,
                                         BranchPair, ForkPointOverrideData,
                                         FullCommitHash, GitContext,
                                         LocalBranchShortName,
                                         RemoteBranchShortName,
                                         SyncToRemoteStatus)
-from git_machete.utils import (bold, debug, dim, excluding, flat_map, fmt,
-                               get_pretty_choices, get_second,
-                               join_paths_posix, relpath_posix, tupled, warn)
+from git_machete.utils import (InteractionStopped, MacheteException,
+                               UnexpectedMacheteException, bold, debug, dim,
+                               excluding, flat_map, fmt, get_pretty_choices,
+                               get_second, join_paths_posix, relpath_posix,
+                               tupled, warn)
 
 
 class PickRoot(Enum):
diff --git a/git_machete/client/discover.py b/git_machete/client/discover.py
@@ -6,10 +6,9 @@
 from git_machete.client.status import StatusMacheteClient
 from git_machete.config import SquashMergeDetection
 from git_machete.constants import DISCOVER_DEFAULT_FRESH_BRANCH_COUNT
-from git_machete.exceptions import MacheteException
 from git_machete.git_operations import LocalBranchShortName
-from git_machete.utils import (bold, debug, excluding, get_pretty_choices,
-                               slurp_file, tupled, warn)
+from git_machete.utils import (MacheteException, bold, debug, excluding,
+                               get_pretty_choices, slurp_file, tupled, warn)
 
 
 class DiscoverMacheteClient(StatusMacheteClient):
diff --git a/git_machete/client/fork_point.py b/git_machete/client/fork_point.py
@@ -1,7 +1,6 @@
 from git_machete.client.base import MacheteClient
-from git_machete.exceptions import MacheteException
 from git_machete.git_operations import AnyRevision, LocalBranchShortName
-from git_machete.utils import bold, fmt
+from git_machete.utils import MacheteException, bold, fmt
 
 
 class ForkPointMacheteClient(MacheteClient):
diff --git a/git_machete/client/go_interactive.py b/git_machete/client/go_interactive.py
@@ -12,9 +12,9 @@
 from git_machete import utils
 from git_machete.client.status import (StatusData, StatusFlags,
                                        StatusMacheteClient)
-from git_machete.exceptions import MacheteException, UnexpectedMacheteException
 from git_machete.git_operations import LocalBranchShortName
-from git_machete.utils import bold, index_or_none, warn
+from git_machete.utils import (MacheteException, UnexpectedMacheteException,
+                               bold, index_or_none, warn)
 
 
 class GoInteractiveMacheteClient(StatusMacheteClient):
diff --git a/git_machete/client/go_show.py b/git_machete/client/go_show.py
@@ -1,8 +1,8 @@
 from typing import List, Optional
 
 from git_machete.client.base import MacheteClient, PickRoot
-from git_machete.exceptions import MacheteException, UnexpectedMacheteException
 from git_machete.git_operations import LocalBranchShortName
+from git_machete.utils import MacheteException, UnexpectedMacheteException
 
 
 class GoShowMacheteClient(MacheteClient):
diff --git a/git_machete/client/slide_out.py b/git_machete/client/slide_out.py
@@ -2,9 +2,9 @@
 
 from git_machete.client.base import MacheteClient
 from git_machete.config import SquashMergeDetection
-from git_machete.exceptions import MacheteException
 from git_machete.git_operations import AnyRevision, LocalBranchShortName
-from git_machete.utils import bold, fmt, green_ok, print_no_newline
+from git_machete.utils import (MacheteException, bold, fmt, green_ok,
+                               print_no_newline)
 
 
 class SlideOutMacheteClient(MacheteClient):
diff --git a/git_machete/client/squash.py b/git_machete/client/squash.py
@@ -2,11 +2,10 @@
 from typing import List
 
 from git_machete.client.base import MacheteClient
-from git_machete.exceptions import MacheteException
 from git_machete.git_operations import (AnyRevision, FullCommitHash,
                                         GitFormatPatterns, GitLogEntry,
                                         LocalBranchShortName)
-from git_machete.utils import bold, fmt
+from git_machete.utils import MacheteException, bold, fmt
 
 
 class SquashMacheteClient(MacheteClient):
diff --git a/git_machete/client/status.py b/git_machete/client/status.py
@@ -9,12 +9,11 @@
 from git_machete import utils
 from git_machete.annotation import Annotation
 from git_machete.config import SquashMergeDetection
-from git_machete.exceptions import MacheteException
 from git_machete.git_operations import (BranchPair, FullCommitHash,
                                         GitLogEntry, LocalBranchShortName,
                                         SyncToRemoteStatus)
-from git_machete.utils import (PopenResult, bold, colored, debug, dim,
-                               underline, warn)
+from git_machete.utils import (MacheteException, PopenResult, bold, colored,
+                               debug, dim, underline, warn)
 
 from .base import MacheteClient
 
diff --git a/git_machete/client/traverse.py b/git_machete/client/traverse.py
@@ -8,12 +8,13 @@
 from git_machete.code_hosting import PullRequest
 from git_machete.config import (SquashMergeDetection,
                                 TraverseWhenBranchNotCheckedOutInAnyWorktree)
-from git_machete.exceptions import MacheteException, UnexpectedMacheteException
 from git_machete.git_operations import (GitContext, LocalBranchShortName,
                                         SyncToRemoteStatus)
-from git_machete.utils import (ParsableEnum, abspath_posix, bold, flat_map,
-                               fmt, get_pretty_choices, get_right_arrow,
-                               green_ok, print_no_newline, warn)
+from git_machete.utils import (MacheteException, ParsableEnum,
+                               UnexpectedMacheteException, abspath_posix, bold,
+                               flat_map, fmt, get_pretty_choices,
+                               get_right_arrow, green_ok, print_no_newline,
+                               warn)
 
 
 class TraverseReturnTo(ParsableEnum):
diff --git a/git_machete/client/with_code_hosting.py b/git_machete/client/with_code_hosting.py
@@ -10,12 +10,12 @@
                                       OrganizationAndRepositoryAndRemote,
                                       PullRequest, is_matching_remote_url)
 from git_machete.config import PRDescriptionIntroStyle, SquashMergeDetection
-from git_machete.exceptions import MacheteException, UnexpectedMacheteException
 from git_machete.git_operations import (GitContext, GitFormatPatterns,
                                         GitLogEntry, LocalBranchShortName,
                                         RemoteBranchShortName,
                                         SyncToRemoteStatus)
-from git_machete.utils import (bold, colored_yes_no, debug, find_or_none, fmt,
+from git_machete.utils import (MacheteException, UnexpectedMacheteException,
+                               bold, colored_yes_no, debug, find_or_none, fmt,
                                get_pretty_choices, get_right_arrow, green_ok,
                                join_paths_posix, print_no_newline, slurp_file,
                                warn)
diff --git a/git_machete/exceptions.py b/git_machete/exceptions.py
diff --git a/git_machete/git_operations.py b/git_machete/git_operations.py
@@ -10,9 +10,9 @@
 
 from . import utils
 from .constants import MAX_COMMITS_FOR_SQUASH_MERGE_DETECTION
-from .exceptions import UnderlyingGitException, UnexpectedMacheteException
-from .utils import (CommandResult, abspath_posix, colored, debug, fmt,
-                    hex_repr, join_paths_posix, slurp_file)
+from .utils import (CommandResult, UnderlyingGitException,
+                    UnexpectedMacheteException, abspath_posix, colored, debug,
+                    fmt, hex_repr, join_paths_posix, slurp_file)
 
 
 class AnyRevision(str):
diff --git a/git_machete/github.py b/git_machete/github.py
@@ -16,9 +16,9 @@
                                       OrganizationAndRepository,
                                       OrganizationAndRepositoryAndGitUrl,
                                       PullRequest)
-from git_machete.exceptions import MacheteException, UnexpectedMacheteException
 from git_machete.git_operations import LocalBranchShortName
-from git_machete.utils import (bold, compact_dict, debug, join_paths_posix,
+from git_machete.utils import (MacheteException, UnexpectedMacheteException,
+                               bold, compact_dict, debug, join_paths_posix,
                                popen_cmd, warn)
 
 GITHUB_TOKEN_ENV_VAR = 'GITHUB_TOKEN'
diff --git a/git_machete/gitlab.py b/git_machete/gitlab.py
@@ -16,9 +16,9 @@
                                       OrganizationAndRepository,
                                       OrganizationAndRepositoryAndGitUrl,
                                       PullRequest)
-from git_machete.exceptions import MacheteException, UnexpectedMacheteException
 from git_machete.git_operations import LocalBranchShortName
-from git_machete.utils import compact_dict, debug, map_truthy_only, popen_cmd
+from git_machete.utils import (MacheteException, UnexpectedMacheteException,
+                               compact_dict, debug, map_truthy_only, popen_cmd)
 
 GITLAB_TOKEN_ENV_VAR = 'GITLAB_TOKEN'
 
diff --git a/git_machete/utils.py b/git_machete/utils.py
@@ -6,30 +6,16 @@
 import sys
 import textwrap
 import time
-from enum import Enum
+from enum import Enum, IntEnum
 from pathlib import Path, PurePosixPath
 from typing import (Any, Callable, Dict, Iterable, List, NamedTuple, Optional,
                     Sequence, Set, Tuple, Type, TypeVar)
 
-from git_machete.exceptions import MacheteException
-
 T = TypeVar('T')
 U = TypeVar('U')
 E = TypeVar('E', bound=Enum)
 
 
-class ParsableEnum(Enum):
-    @classmethod
-    def from_string(cls: Type[E], value: str, from_where: Optional[str]) -> E:
-        try:
-            return cls[value.upper().replace("-", "_")]
-        except KeyError:
-            valid_values = ', '.join('`' + e.name.lower().replace("_", "-") + '`' for e in cls)
-            prefix = f"Invalid value for {from_where}" if from_where else "Invalid value"
-            printed_value = value or '<empty>'
-            raise MacheteException(f"{prefix}: `{printed_value}`. Valid values are {valid_values}")
-
-
 # To avoid displaying the same warning multiple times during a single run.
 displayed_warnings: Set[str] = set()
 
@@ -481,6 +467,55 @@ def fmt(*parts: str) -> str:
     return result
 
 
+NEW_ISSUE_LINK = "https://github.com/VirtusLab/git-machete/issues/new"
+
+
+class InteractionStopped(Exception):
+    def __init__(self) -> None:
+        pass
+
+
+class UnderlyingGitException(Exception):
+    def __init__(self, msg: str, *, apply_fmt: bool = True) -> None:
+        self.msg: str = fmt(msg) if apply_fmt else msg
+
+    def __str__(self) -> str:
+        return str(self.msg)
+
+
+class MacheteException(Exception):
+    def __init__(self, msg: str, *, apply_fmt: bool = True) -> None:
+        self.msg: str = fmt(msg) if apply_fmt else msg
+
+    def __str__(self) -> str:
+        return str(self.msg)
+
+
+class UnexpectedMacheteException(MacheteException):
+    def __init__(self, msg: str, *, apply_fmt: bool = True) -> None:
+        super().__init__(f"{msg}\n\nConsider posting an issue at `{NEW_ISSUE_LINK}`", apply_fmt=apply_fmt)
+
+
+class ExitCode(IntEnum):
+    SUCCESS = 0
+    MACHETE_EXCEPTION = 1
+    ARGUMENT_ERROR = 2
+    KEYBOARD_INTERRUPT = 3
+    END_OF_FILE_SIGNAL = 4
+
+
+class ParsableEnum(Enum):
+    @classmethod
+    def from_string(cls: Type[E], value: str, from_where: Optional[str]) -> E:
+        try:
+            return cls[value.upper().replace("-", "_")]
+        except KeyError:
+            valid_values = ', '.join('`' + e.name.lower().replace("_", "-") + '`' for e in cls)
+            prefix = f"Invalid value for {from_where}" if from_where else "Invalid value"
+            printed_value = value or '<empty>'
+            raise MacheteException(f"{prefix}: `{printed_value}`. Valid values are {valid_values}")
+
+
 def get_vertical_bar() -> str:
     return "|" if ascii_only else "│"
 
diff --git a/requirements/cyclic-import-check.txt b/requirements/cyclic-import-check.txt
@@ -0,0 +1 @@
+pylint==4.0.5
diff --git a/tests/mockers.py b/tests/mockers.py
@@ -12,8 +12,7 @@
 import pytest
 
 from git_machete import cli, utils
-from git_machete.exceptions import MacheteException
-from git_machete.utils import PopenResult
+from git_machete.utils import MacheteException, PopenResult
 
 
 @contextmanager
diff --git a/tests/test_advance.py b/tests/test_advance.py
@@ -1,6 +1,6 @@
 from pytest_mock import MockerFixture
 
-from git_machete.exceptions import ExitCode, UnderlyingGitException
+from git_machete.utils import ExitCode, UnderlyingGitException
 
 from .base_test import BaseTest
 from .mockers import (assert_failure, assert_success, launch_command,
diff --git a/tests/test_cli.py b/tests/test_cli.py
@@ -5,7 +5,7 @@
 from pytest_mock import MockerFixture
 
 from git_machete.cli import alias_by_command, main
-from git_machete.exceptions import ExitCode
+from git_machete.utils import ExitCode
 
 from .base_test import BaseTest
 from .mockers import launch_command_capturing_output_and_exception
diff --git a/tests/test_file.py b/tests/test_file.py
@@ -2,7 +2,7 @@
 from pathlib import Path
 from tempfile import mkdtemp
 
-from git_machete.exceptions import UnderlyingGitException
+from git_machete.utils import UnderlyingGitException
 
 from .base_test import BaseTest
 from .mockers import assert_failure, execute, launch_command
diff --git a/tests/test_github.py b/tests/test_github.py
diff --git a/tests/test_gitlab.py b/tests/test_gitlab.py
diff --git a/tests/test_go.py b/tests/test_go.py
diff --git a/tests/test_help.py b/tests/test_help.py
diff --git a/tests/test_list.py b/tests/test_list.py
diff --git a/tests/test_show.py b/tests/test_show.py
diff --git a/tests/test_traverse.py b/tests/test_traverse.py
diff --git a/tests/test_update.py b/tests/test_update.py
diff --git a/tox.ini b/tox.ini
