git-muster 0.3.1__tar.gz → 0.4.0__tar.gz

{git_muster-0.3.1 → git_muster-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-muster
-Version: 0.3.1
+Version: 0.4.0
 Summary: See every local Git branch and what needs attention
 Keywords: branch,cli,git,github,worktree
 Author: Dan O'Leary
@@ -19,13 +19,15 @@ Requires-Python: >=3.13, <3.15
 Project-URL: Homepage, https://github.com/olearydj/git-muster
 Project-URL: Repository, https://github.com/olearydj/git-muster
 Project-URL: Issues, https://github.com/olearydj/git-muster/issues
+Project-URL: Changelog, https://github.com/olearydj/git-muster/blob/main/CHANGELOG.md
 Description-Content-Type: text/markdown
 
 # git-muster
 
 [![CI](https://github.com/olearydj/git-muster/actions/workflows/ci.yml/badge.svg)](https://github.com/olearydj/git-muster/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/git-muster?logo=pypi&logoColor=white)](https://pypi.org/project/git-muster/)
 [![Python 3.13–3.14](https://img.shields.io/badge/python-3.13%E2%80%933.14-blue.svg)](https://www.python.org/)
-[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/olearydj/git-muster/blob/main/LICENSE)
 
 Every branch, present and accounted for.
 
@@ -61,18 +63,20 @@ BRANCH (4 local)      REMOTE  STATE          WORKTREE       UPDATED  PULL REQUES
 ## Requirements
 
 - Python 3.13 or 3.14
-- Git
+- Git 2.23 or newer, for `git branch --show-current` and `for-each-ref`'s `%(worktreepath)`
 - [uv](https://docs.astral.sh/uv/) for the recommended installation
 - Optional: an authenticated [GitHub CLI](https://cli.github.com/) for pull-request information
 
 ## Install
 
-Install the latest version directly from GitHub:
+Install the latest release from PyPI:
 
 ```console
-uv tool install git+https://github.com/olearydj/git-muster.git
+uv tool install git-muster
 ```
 
+Use `uv tool upgrade git-muster` to update an existing installation.
+
 The installed commands are equivalent:
 
 ```console
@@ -98,7 +102,7 @@ Run the report from anywhere inside a Git repository:
 git muster
 ```
 
-By default, Git Muster runs `git fetch --all --prune --quiet` before reporting so remote-tracking references are current. Skip all network activity and repository mutation with:
+By default, Git Muster runs `git fetch --all --prune --quiet` before reporting so remote-tracking references are current. When that fetch fails, because the machine is offline or a remote no longer answers, the report still renders from the references already on disk and says that branch states may be out of date. Skip all network activity and repository mutation with:
 
 ```console
 git muster --no-fetch
@@ -117,6 +121,18 @@ git muster --help
 git muster --version
 ```
 
+### Color, symbols, and width
+
+Color, Unicode symbols, and clickable pull-request numbers appear when the report is written to an interactive terminal that can render them. Git Muster honors the usual overrides:
+
+| Variable | Effect |
+|---|---|
+| `NO_COLOR` | Disables color; symbols and layout are unchanged. |
+| `FORCE_COLOR`, `CLICOLOR_FORCE` | Keep color when output is redirected to a file or pipe. |
+| `COLUMNS` | Overrides the detected terminal width used to fit columns. |
+
+`--plain` overrides all of them and emits pure ASCII, without color or terminal hyperlinks. Git Muster also falls back to those ASCII glyphs on its own whenever the destination stream cannot encode its symbols, so redirected output never fails to encode.
+
 ## Reading the report
 
 | Column | Meaning |
@@ -141,7 +157,7 @@ Publication is deliberately separate from Git's configured upstream. A branch is
 
 When another linked worktree holds a branch, Git Muster shows its directory in the table and lists the full checkout path below it. It does not scan those other worktrees for dirtiness or change them.
 
-GitHub integration uses one optional `gh pr list` query. Without an installed and authenticated `gh`, the complete Git report still works and explains why PR status is unavailable.
+GitHub integration uses one optional `gh pr list --state all --limit 100` query, so a branch whose pull request falls outside the hundred most recent is reported without pull-request state. When several pull requests share a head branch, the newest open, draft, approved, or changes-requested one wins over closed and merged ones. Without an installed and authenticated `gh`, or when no remote points at a known GitHub host, the complete Git report still works and names the reason pull-request state is missing.
 
 ## Safety and scope
 
@@ -162,8 +178,14 @@ uv run --locked ty check
 uv build
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. CI runs the same checks on Python 3.13 and 3.14.
+See [CONTRIBUTING.md](https://github.com/olearydj/git-muster/blob/main/CONTRIBUTING.md) before opening a pull request. CI runs the same checks on Python 3.13 and 3.14.
+
+## Project documents
+
+- [CHANGELOG.md](https://github.com/olearydj/git-muster/blob/main/CHANGELOG.md) for release history.
+- [CONTRIBUTING.md](https://github.com/olearydj/git-muster/blob/main/CONTRIBUTING.md) for development and release steps.
+- [SECURITY.md](https://github.com/olearydj/git-muster/blob/main/SECURITY.md) for reporting a vulnerability.
 
 ## License
 
-Git Muster is available under the [MIT License](LICENSE).
+Git Muster is available under the [MIT License](https://github.com/olearydj/git-muster/blob/main/LICENSE).

{git_muster-0.3.1 → git_muster-0.4.0}/README.md

@@ -1,8 +1,9 @@
 # git-muster
 
 [![CI](https://github.com/olearydj/git-muster/actions/workflows/ci.yml/badge.svg)](https://github.com/olearydj/git-muster/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/git-muster?logo=pypi&logoColor=white)](https://pypi.org/project/git-muster/)
 [![Python 3.13–3.14](https://img.shields.io/badge/python-3.13%E2%80%933.14-blue.svg)](https://www.python.org/)
-[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/olearydj/git-muster/blob/main/LICENSE)
 
 Every branch, present and accounted for.
 
@@ -38,18 +39,20 @@ BRANCH (4 local)      REMOTE  STATE          WORKTREE       UPDATED  PULL REQUES
 ## Requirements
 
 - Python 3.13 or 3.14
-- Git
+- Git 2.23 or newer, for `git branch --show-current` and `for-each-ref`'s `%(worktreepath)`
 - [uv](https://docs.astral.sh/uv/) for the recommended installation
 - Optional: an authenticated [GitHub CLI](https://cli.github.com/) for pull-request information
 
 ## Install
 
-Install the latest version directly from GitHub:
+Install the latest release from PyPI:
 
 ```console
-uv tool install git+https://github.com/olearydj/git-muster.git
+uv tool install git-muster
 ```
 
+Use `uv tool upgrade git-muster` to update an existing installation.
+
 The installed commands are equivalent:
 
 ```console
@@ -75,7 +78,7 @@ Run the report from anywhere inside a Git repository:
 git muster
 ```
 
-By default, Git Muster runs `git fetch --all --prune --quiet` before reporting so remote-tracking references are current. Skip all network activity and repository mutation with:
+By default, Git Muster runs `git fetch --all --prune --quiet` before reporting so remote-tracking references are current. When that fetch fails, because the machine is offline or a remote no longer answers, the report still renders from the references already on disk and says that branch states may be out of date. Skip all network activity and repository mutation with:
 
 ```console
 git muster --no-fetch
@@ -94,6 +97,18 @@ git muster --help
 git muster --version
 ```
 
+### Color, symbols, and width
+
+Color, Unicode symbols, and clickable pull-request numbers appear when the report is written to an interactive terminal that can render them. Git Muster honors the usual overrides:
+
+| Variable | Effect |
+|---|---|
+| `NO_COLOR` | Disables color; symbols and layout are unchanged. |
+| `FORCE_COLOR`, `CLICOLOR_FORCE` | Keep color when output is redirected to a file or pipe. |
+| `COLUMNS` | Overrides the detected terminal width used to fit columns. |
+
+`--plain` overrides all of them and emits pure ASCII, without color or terminal hyperlinks. Git Muster also falls back to those ASCII glyphs on its own whenever the destination stream cannot encode its symbols, so redirected output never fails to encode.
+
 ## Reading the report
 
 | Column | Meaning |
@@ -118,7 +133,7 @@ Publication is deliberately separate from Git's configured upstream. A branch is
 
 When another linked worktree holds a branch, Git Muster shows its directory in the table and lists the full checkout path below it. It does not scan those other worktrees for dirtiness or change them.
 
-GitHub integration uses one optional `gh pr list` query. Without an installed and authenticated `gh`, the complete Git report still works and explains why PR status is unavailable.
+GitHub integration uses one optional `gh pr list --state all --limit 100` query, so a branch whose pull request falls outside the hundred most recent is reported without pull-request state. When several pull requests share a head branch, the newest open, draft, approved, or changes-requested one wins over closed and merged ones. Without an installed and authenticated `gh`, or when no remote points at a known GitHub host, the complete Git report still works and names the reason pull-request state is missing.
 
 ## Safety and scope
 
@@ -139,8 +154,14 @@ uv run --locked ty check
 uv build
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. CI runs the same checks on Python 3.13 and 3.14.
+See [CONTRIBUTING.md](https://github.com/olearydj/git-muster/blob/main/CONTRIBUTING.md) before opening a pull request. CI runs the same checks on Python 3.13 and 3.14.
+
+## Project documents
+
+- [CHANGELOG.md](https://github.com/olearydj/git-muster/blob/main/CHANGELOG.md) for release history.
+- [CONTRIBUTING.md](https://github.com/olearydj/git-muster/blob/main/CONTRIBUTING.md) for development and release steps.
+- [SECURITY.md](https://github.com/olearydj/git-muster/blob/main/SECURITY.md) for reporting a vulnerability.
 
 ## License
 
-Git Muster is available under the [MIT License](LICENSE).
+Git Muster is available under the [MIT License](https://github.com/olearydj/git-muster/blob/main/LICENSE).

{git_muster-0.3.1 → git_muster-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "git-muster"
-version = "0.3.1"
+version = "0.4.0"
 description = "See every local Git branch and what needs attention"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"
@@ -42,6 +42,7 @@ gm = "git_muster.cli:entrypoint"
 Homepage = "https://github.com/olearydj/git-muster"
 Repository = "https://github.com/olearydj/git-muster"
 Issues = "https://github.com/olearydj/git-muster/issues"
+Changelog = "https://github.com/olearydj/git-muster/blob/main/CHANGELOG.md"
 
 [dependency-groups]
 dev = [
@@ -52,6 +53,7 @@ dev = [
 ]
 
 [tool.uv]
+required-version = ">=0.12.1,<0.13"
 exclude-newer = "3 days"
 
 [tool.pytest.ini_options]

{git_muster-0.3.1 → git_muster-0.4.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "git-muster"
-version = "0.3.1"
+version = "0.4.0"
 description = "See every local Git branch and what needs attention"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"
@@ -31,11 +31,14 @@ gm = "git_muster.cli:entrypoint"
 Homepage = "https://github.com/olearydj/git-muster"
 Repository = "https://github.com/olearydj/git-muster"
 Issues = "https://github.com/olearydj/git-muster/issues"
+Changelog = "https://github.com/olearydj/git-muster/blob/main/CHANGELOG.md"
 
 [dependency-groups]
 dev = ["pytest>=8.4,<10", "pytest-cov>=6,<8", "ruff>=0.12,<1", "ty>=0.0.1a20"]
 
 [tool.uv]
+# Bound the front end as well as the build backend so local and CI resolution match.
+required-version = ">=0.12.1,<0.13"
 # Keep the cooldown in the project because uv records it in uv.lock.
 exclude-newer = "3 days"
 

{git_muster-0.3.1 → git_muster-0.4.0}/src/git_muster/__main__.py

@@ -2,5 +2,5 @@
 
 from git_muster.cli import entrypoint
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover - exercised through a subprocess
     entrypoint()

{git_muster-0.3.1 → git_muster-0.4.0}/src/git_muster/cli.py

@@ -51,6 +51,58 @@ The default run executes [cyan]git fetch --all --prune[/cyan]. It never switches
 merges, rebases, or pushes branches. Use [cyan]--no-fetch[/cyan] for a fully read-only run.
 """
 
+SYMBOL_GLYPHS = {
+    "current": "▸",
+    "synced": "✓",
+    "ahead": "↑",
+    "behind": "↓",
+    "diverged": "⇅",
+    "gone": "✕",
+    "local": "·",
+    "rule": "─",
+    "ellipsis": "…",
+    "notice": "▲",
+    "separator": "·",
+}
+
+ASCII_GLYPHS = {
+    "current": ">",
+    "synced": "=",
+    "ahead": "^",
+    "behind": "v",
+    "diverged": "x",
+    "gone": "!",
+    "local": ".",
+    "rule": "-",
+    "ellipsis": "..",
+    "notice": "!",
+    "separator": "|",
+}
+
+PR_LIMIT = 100
+PR_FIELDS = "headRefName,number,state,isDraft,reviewDecision,url"
+ACTIVE_PR_STATES = {"draft", "open", "approved", "changes requested"}
+
+PR_NOTICES: dict[str, tuple[str, ...]] = {
+    "missing": (
+        "Pull request state unknown - the GitHub CLI is not installed.",
+        "  Install it from https://cli.github.com, then run: gh auth login",
+    ),
+    "unauthenticated": (
+        "Pull request state unknown - the GitHub CLI is not logged in.",
+        "  Run: gh auth login",
+    ),
+    "not-github": ("Pull request state unknown - no remote points at a known GitHub host.",),
+    "unreachable": (
+        "Pull request state unknown - the GitHub CLI could not reach GitHub.",
+        "  Run: gh pr list --state all --limit 1",
+    ),
+    "unusable": (
+        "Pull request state unknown - the GitHub CLI returned unexpected data.",
+        "  Run: gh pr list --state all --limit 1",
+    ),
+}
+
 
 def branch_states_table() -> Table:
     """Build the branch-state reference shown in command help."""
@@ -90,30 +142,72 @@ app = typer.Typer(
 )
 
 
-def command_output(command: str, *args: str) -> str | None:
-    """Run a command quietly, returning ``None`` when it is unavailable or fails."""
+def command_result(command: str, *args: str) -> tuple[int, str, str] | None:
+    """Run a command, returning its status and streams, or ``None`` when it is unavailable."""
     try:
-        result = subprocess.run(
+        completed = subprocess.run(
             [command, *args],
             stdin=subprocess.DEVNULL,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.DEVNULL,
+            capture_output=True,
             text=True,
             check=False,
         )
     except OSError:
         return None
-    if result.returncode != 0:
+    return completed.returncode, completed.stdout.rstrip("\r\n"), completed.stderr.strip()
+
+
+def command_output(command: str, *args: str) -> str | None:
+    """Run a command quietly, returning ``None`` when it is unavailable or fails."""
+    result = command_result(command, *args)
+    if result is None or result[0] != 0:
         return None
-    return result.stdout.rstrip("\r\n")
+    return result[1]
 
 
 def git_output(*args: str) -> str:
     """Run a required Git command or raise a concise operational error."""
-    output = command_output("git", *args)
-    if output is None:
-        raise RuntimeError(f"git {' '.join(args)} failed")
-    return output
+    result = command_result("git", *args)
+    if result is None:
+        raise RuntimeError(f"git {' '.join(args)} failed: git is not installed")
+    code, stdout, stderr = result
+    if code != 0:
+        detail = stderr.splitlines()[0] if stderr else f"exit status {code}"
+        raise RuntimeError(f"git {' '.join(args)} failed: {detail}")
+    return stdout
+
+
+def stream_supports(text: str, stream: Any) -> bool:
+    """Report whether a text stream can encode every character in ``text``."""
+    encoding = getattr(stream, "encoding", None)
+    if not encoding:
+        return True
+    try:
+        text.encode(encoding)
+    except (LookupError, UnicodeEncodeError):
+        return False
+    return True
+
+
+def enable_ansi_escapes() -> bool:
+    """Turn on virtual-terminal processing where needed and report ANSI support."""
+    if sys.platform != "win32":
+        return True
+    if not sys.stdout.isatty():
+        # Redirected output has no console mode to configure, so leave the
+        # decision to --plain, NO_COLOR, and FORCE_COLOR.
+        return True
+    try:  # pragma: no cover - Windows-only console setup
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.GetStdHandle(-11)
+        mode = ctypes.c_uint32()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        return bool(kernel32.SetConsoleMode(handle, mode.value | 0x0004))
+    except (AttributeError, OSError, ValueError):  # pragma: no cover - defensive
+        return False
 
 
 def compact_age(relative: str) -> str:
@@ -125,13 +219,16 @@ def compact_age(relative: str) -> str:
 
 
 def fit(value: str, limit: int, ellipsis: str) -> str:
-    """Middle-truncate text while retaining its recognizable ending."""
+    """Middle-truncate text to exactly ``limit`` cells, retaining its recognizable ending."""
     if len(value) <= limit:
         return value
-    if limit <= 3:
+    if limit <= len(ellipsis):
         return value[:limit]
-    keep_end = max(4, int((limit - 1) * 0.6))
-    keep_start = limit - 1 - keep_end
+    budget = limit - len(ellipsis)
+    keep_end = max(1, int(budget * 0.6))
+    keep_start = budget - keep_end
+    if keep_start <= 0:
+        return ellipsis + value[-budget:]
     return value[:keep_start] + ellipsis + value[-keep_end:]
 
 
@@ -173,13 +270,13 @@ def hyperlink(text: str, url: str, *, enabled: bool) -> str:
 
 def pull_request_status(row: dict[str, object]) -> str:
     """Normalize GitHub's PR and review fields into a compact status."""
-    if row.get("isDraft"):
-        return "draft"
     state = str(row.get("state", "")).upper()
     if state == "MERGED":
         return "merged"
     if state == "CLOSED":
         return "closed"
+    if row.get("isDraft"):
+        return "draft"
     decision = str(row.get("reviewDecision", "")).upper()
     if decision == "APPROVED":
         return "approved"
@@ -188,6 +285,39 @@ def pull_request_status(row: dict[str, object]) -> str:
     return "open"
 
 
+def github_failure(code: int, stderr: str) -> str:
+    """Classify why the GitHub CLI refused to report pull requests."""
+    message = stderr.lower()
+    if (
+        "no git remotes" in message
+        or "known github host" in message
+        or "not a git repository" in message
+    ):
+        return "not-github"
+    if code == 4 or "gh auth login" in message or "authentication" in message:
+        return "unauthenticated"
+    return "unreachable"
+
+
+def github_pull_requests() -> tuple[list[dict[str, object]], str | None]:
+    """Read pull requests through the GitHub CLI, explaining any failure."""
+    result = command_result(
+        "gh", "pr", "list", "--state", "all", "--limit", str(PR_LIMIT), "--json", PR_FIELDS
+    )
+    if result is None:
+        return [], "missing"
+    code, stdout, stderr = result
+    if code != 0:
+        return [], github_failure(code, stderr)
+    try:
+        parsed = json.loads(stdout)
+    except (json.JSONDecodeError, TypeError, ValueError):
+        return [], "unusable"
+    if not isinstance(parsed, list):
+        return [], "unusable"
+    return [row for row in parsed if isinstance(row, dict)], None
+
+
 def parse_track(track: str) -> tuple[int, int] | None:
     """Return ahead/behind counts from Git's tracking decoration."""
     if "gone" in track:
@@ -244,14 +374,27 @@ def run_report(*, no_fetch: bool = False, plain: bool = False) -> int:
         print("git muster: current directory is not inside a Git repository", file=sys.stderr)
         return 2
 
-    use_colour = not plain and sys.stdout.isatty() and not bool(os.environ.get("NO_COLOR"))
-    use_links = not plain and sys.stdout.isatty()
+    interactive = sys.stdout.isatty()
+    ansi_ready = enable_ansi_escapes()
+    forced_colour = bool(os.environ.get("FORCE_COLOR") or os.environ.get("CLICOLOR_FORCE"))
+    use_colour = (
+        not plain
+        and ansi_ready
+        and not os.environ.get("NO_COLOR")
+        and (interactive or forced_colour)
+    )
+    use_links = not plain and ansi_ready and interactive
     modern_terminal = sys.platform != "win32" or bool(
         os.environ.get("WT_SESSION")
         or os.environ.get("TERM_PROGRAM")
         or os.environ.get("TERMINAL_EMULATOR")
     )
-    use_symbols = not plain and modern_terminal
+    use_symbols = (
+        not plain
+        and modern_terminal
+        and stream_supports("".join(SYMBOL_GLYPHS.values()), sys.stdout)
+    )
+    glyph = SYMBOL_GLYPHS if use_symbols else ASCII_GLYPHS
 
     def paint(code: str) -> Callable[[str], str]:
         return lambda text: f"\033[{code}m{text}\033[0m" if use_colour else text
@@ -263,86 +406,56 @@ def run_report(*, no_fetch: bool = False, plain: bool = False) -> int:
     yellow = paint("33")
     blue = paint("34")
 
-    if use_symbols:
-        glyph = {
-            "current": "▸",
-            "synced": "✓",
-            "ahead": "↑",
-            "behind": "↓",
-            "diverged": "⇅",
-            "gone": "✕",
-            "local": "·",
-            "rule": "─",
-            "ellipsis": "…",
-            "notice": "▲",
-        }
-    else:
-        glyph = {
-            "current": ">",
-            "synced": "=",
-            "ahead": "^",
-            "behind": "v",
-            "diverged": "x",
-            "gone": "!",
-            "local": ".",
-            "rule": "-",
-            "ellipsis": "..",
-            "notice": "!",
-        }
-
     terminal_width = max(60, min(shutil.get_terminal_size((100, 24)).columns, 160))
 
+    fetch_failed = False
     if not no_fetch:
-        if sys.stdout.isatty():
+        if interactive:
             print(dim("fetching..."), end="", flush=True)
-        command_output("git", "fetch", "--all", "--prune", "--quiet")
-        if sys.stdout.isatty():
+        fetch_failed = command_output("git", "fetch", "--all", "--prune", "--quiet") is None
+        if interactive:
             print("\r           \r", end="", flush=True)
 
     default_branch = command_output("git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD")
     default_branch = default_branch.removeprefix("origin/") if default_branch else "main"
 
+    pr_rows, pr_reason = github_pull_requests()
     pull_requests: dict[str, PullRequest] = {}
-    pr_json = command_output(
-        "gh",
-        "pr",
-        "list",
-        "--state",
-        "all",
-        "--limit",
-        "100",
-        "--json",
-        "headRefName,number,state,isDraft,reviewDecision,url",
-    )
-    if pr_json is not None:
-        try:
-            pr_rows = json.loads(pr_json)
-        except (json.JSONDecodeError, TypeError):
-            pr_json = None
-        else:
-            for pr in pr_rows:
-                name = pr.get("headRefName")
-                if not name or name == default_branch or name in pull_requests:
-                    continue
-                state = pull_request_status(pr)
-                colour = (
-                    green
-                    if state in {"approved", "merged"}
-                    else red
-                    if state == "changes requested"
-                    else yellow
-                    if state == "draft"
-                    else dim
-                    if state == "closed"
-                    else blue
-                )
-                number = pr.get("number")
-                pull_requests[name] = PullRequest(
-                    f"#{number} {state}",
-                    colour,
-                    number if isinstance(number, int) else None,
-                    str(pr.get("url", "")),
-                )
+    pr_ranks: dict[str, tuple[bool, int]] = {}
+    usable_rows = 0
+    for row in pr_rows:
+        name = row.get("headRefName")
+        number = row.get("number")
+        # bool is a subclass of int, so the number's type is compared exactly.
+        if not isinstance(name, str) or not name or type(number) is not int or number <= 0:
+            continue
+        usable_rows += 1
+        if name == default_branch:
+            continue
+        state = pull_request_status(row)
+        rank = (state in ACTIVE_PR_STATES, number)
+        if name in pr_ranks and pr_ranks[name] >= rank:
+            continue
+        colour = (
+            green
+            if state in {"approved", "merged"}
+            else red
+            if state == "changes requested"
+            else yellow
+            if state == "draft"
+            else dim
+            if state == "closed"
+            else blue
+        )
+        pr_ranks[name] = rank
+        pull_requests[name] = PullRequest(
+            f"#{number} {state}",
+            colour,
+            number,
+            str(row.get("url", "")),
+        )
+    if pr_rows and not usable_rows:
+        pr_reason = "unusable"
 
     current = command_output("git", "branch", "--show-current") or ""
     dirty = git_output("status", "--short", "--untracked-files=all")
@@ -450,7 +563,7 @@ def run_report(*, no_fetch: bool = False, plain: bool = False) -> int:
         return max([len(heading), *(len(value) for value in values)]) + 2 + extra
 
     branch_heading = f"BRANCH ({len(branches)} local)"
-    show_pr = pr_json is not None
+    show_pr = pr_reason is None
     show_worktree = any(branch.worktree for branch in branches)
     pr_width = (
         max([len("PULL REQUEST"), *(len(branch.pull_request.text) for branch in branches)])
@@ -509,8 +622,10 @@ def run_report(*, no_fetch: bool = False, plain: bool = False) -> int:
 
     print()
     print(bold(repo_name) + dim(" :: ") + bold(current or "detached HEAD"))
-    joiner = " · " if use_symbols else " | "
-    worktree = yellow(f"dirty: {joiner.join(worktree_parts)}") if dirty_lines else green("clean")
+    separator = glyph["separator"]
+    worktree = (
+        yellow(f"dirty: {f' {separator} '.join(worktree_parts)}") if dirty_lines else green("clean")
+    )
     print(dim("worktree, ") + worktree)
     print(dim(glyph["rule"] * total_width))
     heading = (
@@ -520,7 +635,10 @@ def run_report(*, no_fetch: bool = False, plain: bool = False) -> int:
     )
     if show_worktree:
         heading += pad("WORKTREE", columns["worktree"])
-    heading += pad("UPDATED", columns["updated"]) + "PULL REQUEST" if show_pr else "UPDATED"
+    if show_pr:
+        heading += pad("UPDATED", columns["updated"]) + "PULL REQUEST"
+    else:
+        heading += "UPDATED"
     print(dim(heading))
 
     for branch in branches:
@@ -528,36 +646,38 @@ def run_report(*, no_fetch: bool = False, plain: bool = False) -> int:
         name = fit(branch.name, columns["name"] - 3, glyph["ellipsis"])
         name_padding = " " * max(0, columns["name"] - len(marker) - len(name))
         updated = compact_age(branch.updated) if compact_dates else branch.updated
-        row = marker + paint_branch(name, branch.is_current) + name_padding
-        row += dim(
+        row_text = marker + paint_branch(name, branch.is_current) + name_padding
+        row_text += dim(
             pad(
                 fit(branch.remote, columns["remote"] - 2, glyph["ellipsis"]),
                 columns["remote"],
             )
         )
-        row += branch.state_colour(
+        row_text += branch.state_colour(
             pad(f"{branch.state_mark} {branch.state_text}", columns["state"])
         )
         if show_worktree:
             worktree_name = branch.worktree or "-"
-            row += dim(
+            row_text += dim(
                 pad(
                     fit(worktree_name, columns["worktree"] - 2, glyph["ellipsis"]),
                     columns["worktree"],
                 )
             )
         if show_pr:
-            row += dim(pad(updated, columns["updated"]))
+            row_text += dim(pad(updated, columns["updated"]))
             pr = branch.pull_request
             if pr.number is None:
                 rendered_pr = pr.text
             else:
-                number = f"#{pr.number}"
-                rendered_pr = hyperlink(number, pr.url, enabled=use_links) + pr.text[len(number) :]
-            row += pr.colour(rendered_pr)
+                number_text = f"#{pr.number}"
+                rendered_pr = (
+                    hyperlink(number_text, pr.url, enabled=use_links) + pr.text[len(number_text) :]
+                )
+            row_text += pr.colour(rendered_pr)
         else:
-            row += dim(updated)
-        print(row)
+            row_text += dim(updated)
+        print(row_text)
 
     print(dim(glyph["rule"] * total_width))
     linked_worktrees = [branch for branch in branches if branch.worktree_path]
@@ -587,16 +707,19 @@ def run_report(*, no_fetch: bool = False, plain: bool = False) -> int:
     if remote_gone:
         counts.append(f"{remote_gone} remote gone")
     if counts:
-        print(dim("  ·  ".join(counts)))
+        print(dim(f"  {separator}  ".join(counts)))
 
-    if not show_pr:
+    if fetch_failed:
         print()
-        notice = (
-            f"{glyph['notice']} Pull request state unknown - "
-            "the GitHub CLI is missing or not logged in."
-        )
-        print(yellow(notice))
-        print(yellow("  Install it from https://cli.github.com, then run: gh auth login"))
+        print(yellow(f"{glyph['notice']} Fetch failed - branch states may be out of date."))
+        print(yellow("  Check network access and remote configuration, or use --no-fetch."))
+
+    if pr_reason is not None:
+        notice_lines = PR_NOTICES[pr_reason]
+        print()
+        print(yellow(f"{glyph['notice']} {notice_lines[0]}"))
+        for extra_line in notice_lines[1:]:
+            print(yellow(extra_line))
     print()
     return 0