git-nearest 0.1.0__py3-none-any.whl

git_nearest/__init__.py

@@ -0,0 +1,3 @@
+"""Find the remote branches closest to HEAD."""
+
+__version__ = "0.1.0"

git_nearest/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

git_nearest/cli.py

@@ -0,0 +1,64 @@
+import argparse
+import os
+import sys
+
+from . import __version__, color, graph, refs, status, table
+from .color import Painter
+from .gitutil import GitError, git
+
+
+def _parser():
+    p = argparse.ArgumentParser(
+        prog="git nearest",
+        description="List the remote branches closest to HEAD (fewest commits ahead, then fewest behind).",
+    )
+    p.add_argument("limit", nargs="?", type=int, default=5, help="how many refs to show (default: 5)")
+    p.add_argument("-g", "--graph", action="store_true", help="draw how HEAD and those refs relate")
+    p.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    p.add_argument("--no-color", dest="color", action="store_const", const="never", help="same as --color=never")
+    p.add_argument("--no-status", action="store_true", help="don't check the working tree (faster on huge repos)")
+    p.add_argument("--version", action="version", version="git-nearest " + __version__)
+    return p
+
+
+def head_line(note, paint):
+    """The line above the table: where HEAD is and whether the working tree is clean."""
+    if note is None:
+        return None
+    branch = git("symbolic-ref", "--short", "-q", "HEAD", check=False)
+    label = "HEAD -> " + branch if branch else "HEAD (detached)"
+    return "%s  %s  %s" % (paint(color.GREEN_BOLD, "@"), paint(color.GREEN_BOLD, label), note)
+
+
+def _use_color(mode):
+    if mode == "always":
+        return True
+    return mode == "auto" and sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def main(argv=None):
+    args = _parser().parse_args(argv)
+    if args.limit < 1:
+        sys.exit("git-nearest: limit must be at least 1")
+    if os.name == "nt":
+        os.system("")  # turns on ANSI escape handling in the legacy Windows console
+    if not sys.stdout.isatty() and hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+
+    try:
+        git("rev-parse", "--verify", "-q", "HEAD")
+        rows = refs.rank(args.limit)
+        if not rows:
+            print("git-nearest: no remote branches found (try `git fetch`)", file=sys.stderr)
+            return 1
+        paint = Painter(_use_color(args.color))
+        note = None if args.no_status else status.describe(status.read(), paint)
+        if args.graph:
+            lines = graph.render([r.ref for r in rows], paint, note)
+        else:
+            lines = table.render(rows, paint, head_line(note, paint))
+    except GitError as e:
+        print("git-nearest: " + str(e), file=sys.stderr)
+        return 1
+    print("\n".join(lines))
+    return 0

git_nearest/color.py

@@ -0,0 +1,18 @@
+"""ANSI styling that can be switched off."""
+
+DIM = "2"
+GREEN = "32"
+GREEN_BOLD = "1;32"
+RED = "31"
+YELLOW = "33"
+CYAN = "36"
+
+
+class Painter:
+    def __init__(self, enabled):
+        self.enabled = enabled
+
+    def __call__(self, code, text):
+        if not self.enabled or not text:
+            return text
+        return "\033[%sm%s\033[0m" % (code, text)

git_nearest/gitutil.py

@@ -0,0 +1,24 @@
+"""Thin wrapper around the git executable."""
+import subprocess
+
+
+class GitError(Exception):
+    pass
+
+
+def git(*args, check=True, strip=True):
+    """Run git and return stdout (stripped unless strip is False).
+
+    On failure raise GitError, or return "" when check is False.
+    """
+    try:
+        p = subprocess.run(
+            ["git", *args], capture_output=True, text=True, encoding="utf-8", errors="replace"
+        )
+    except FileNotFoundError:
+        raise GitError("git executable not found")
+    if p.returncode != 0:
+        if check:
+            raise GitError(p.stderr.strip() or "git " + " ".join(args) + " failed")
+        return ""
+    return p.stdout.strip() if strip else p.stdout

git_nearest/graph.py

@@ -0,0 +1,155 @@
+"""`jj log`-style graph (newest on top) of HEAD and the given remote refs.
+
+Only the commits that matter are drawn: HEAD, the ref tips and the merge-bases between them.
+Everything in between is folded into a "~  (n)" row on the vertical line.
+"""
+from . import color
+from .gitutil import git
+
+LINE_GLYPHS = set("│├┴┼╯╮┤─~")  # │ ├ ┴ ┼ ╯ ╮ ┤ ─ ~
+LEGEND = "~ (n) = n commits folded between"
+
+
+def render(refs, paint, head_note=None):
+    head = git("rev-parse", "HEAD")
+    branch = git("symbolic-ref", "--short", "-q", "HEAD", check=False)
+    names = {}  # commit -> remote refs pointing at it
+    shas = git("rev-parse", *["refs/remotes/" + r for r in refs]).split()
+    for ref, sha in zip(refs, shas):
+        names.setdefault(sha, []).append(ref)
+    tips = sorted(set(names) | {head})
+    tip_bit = {c: 1 << i for i, c in enumerate(tips)}
+
+    # Load the history above the common base: children come before parents in `order`.
+    base = git("merge-base", "--octopus", *tips, check=False)
+    rev = ["rev-list", "--topo-order", "--parents", *tips] + (["^" + base] if base else [])
+    parents = {}
+    order = []
+    for line in git(*rev).splitlines():
+        commit, *ps = line.split()
+        parents[commit] = ps
+        order.append(commit)
+    if base:
+        parents[base] = []
+        order.append(base)
+    for commit in order:
+        parents[commit] = [p for p in parents[commit] if p in parents]
+
+    # mask[c] = which tips can reach c. Commits sharing a mask form one region; the newest commit
+    # of each region (no child with the same mask) is where branches split: a merge-base.
+    mask = {c: tip_bit.get(c, 0) for c in order}
+    for c in order:
+        for p in parents[c]:
+            mask[p] |= mask[c]
+    has_twin_child = {p for c in order for p in parents[c] if mask[p] == mask[c]}
+    nodes = [c for c in order if c in tip_bit or c not in has_twin_child]
+    node_bit = {c: 1 << i for i, c in enumerate(nodes)}
+
+    # allanc[c] = bitmask of every node below c; the nearest are those no other ancestor node covers.
+    allanc = {}
+    for c in reversed(order):
+        a = 0
+        for p in parents[c]:
+            a |= allanc[p] | node_bit.get(p, 0)
+        allanc[c] = a
+
+    def on_head_line(c):
+        return c == head or bool(allanc[head] & node_bit[c]) or bool(allanc[c] & node_bit[head])
+
+    def sort_key(c):
+        return (not on_head_line(c), sorted(names.get(c, [c]))[0])
+
+    above = {}   # node -> nearest ancestor nodes, head line first
+    folded = {}  # node -> commits between it and those ancestors
+    for c in nodes:
+        a = allanc[c]
+        covered = 0
+        for n in nodes:
+            if a & node_bit[n]:
+                covered |= allanc[n]
+        above[c] = sorted((n for n in nodes if a & ~covered & node_bit[n]), key=sort_key)
+        if above[c]:
+            own = int(git("rev-list", "--count", c, *["^" + p for p in above[c]]) or 1)
+            folded[c] = own - 1
+
+    def node_text(c):
+        parts = []
+        if c == head:
+            parts.append(paint(color.GREEN_BOLD, "HEAD -> " + branch if branch else "HEAD (detached)"))
+        parts += [paint(color.CYAN, n) for n in sorted(names.get(c, []))]
+        if not parts:
+            parts.append(paint(color.DIM, "merge-base"))
+        text = "%s  %s" % (paint(color.DIM, c[:8]), ", ".join(parts))
+        return text + "  " + head_note if c == head and head_note else text
+
+    def marker(c):
+        if c == head:
+            return paint(color.GREEN_BOLD, "@")
+        return paint(color.CYAN if c in names else color.DIM, "○")  # ○
+
+    out = []
+    lanes = []  # lanes[i] = the node lane i is heading to (None = free)
+
+    def emit(cells, fill=(), width=0, text=""):
+        """One row. cells: lane -> glyph (default: a vertical line on an active lane);
+        fill: lanes joined to the next one by a horizontal line."""
+        n = max([i for i, c in enumerate(lanes) if c is not None] + [width - 1, *cells]) + 1
+        row = ""
+        for i in range(n):
+            glyph = cells.get(i) or ("│" if i < len(lanes) and lanes[i] else " ")
+            row += paint(color.DIM, glyph) if glyph in LINE_GLYPHS else glyph
+            row += paint(color.DIM, "─") if i in fill else " "
+        out.append(("%s %s" % (row, text)).rstrip())
+
+    def free_lane(after=-1):
+        for i in range(after + 1, len(lanes)):
+            if lanes[i] is None:
+                return i
+        lanes.append(None)
+        return len(lanes) - 1
+
+    def draw(c):
+        waiting = [i for i, n in enumerate(lanes) if n == c]
+        if not waiting:
+            k = free_lane()
+            lanes[k] = c
+            waiting = [k]
+        k, extra = waiting[0], waiting[1:]
+        if extra:  # lanes of other children converge onto this node
+            cells = {k: "├", **{j: "┴" for j in extra}, extra[-1]: "╯"}
+            for i in range(k + 1, extra[-1]):
+                cells.setdefault(i, "┼" if lanes[i] else "─")
+            emit(cells, fill=range(k, extra[-1]))
+            for j in extra:
+                lanes[j] = None
+        emit({k: marker(c)}, width=k + 1, text=node_text(c))
+
+        ps = above[c]
+        lanes[k] = ps[0] if ps else None
+        for p in ps[1:]:  # merge: a second parent gets its own lane (or joins the one already heading there)
+            joined = p in lanes
+            j = lanes.index(p) if joined else free_lane(k)
+            lanes[j] = p
+            lo, hi = min(k, j), max(k, j)
+            cells = {lo: "├", hi: "┤" if joined else "╮"}
+            for i in range(lo + 1, hi):
+                cells[i] = "┼" if lanes[i] else "─"
+            emit(cells, fill=range(lo, hi))
+        if folded.get(c):
+            emit({k: "~"}, text=paint(color.YELLOW, "(%d)" % folded[c]))
+
+    pending = {c: 0 for c in nodes}
+    for c in nodes:
+        for a in above[c]:
+            pending[a] += 1
+    ready = [c for c in nodes if pending[c] == 0]
+    while ready:
+        ready.sort(key=sort_key)
+        c = ready.pop(0)
+        draw(c)
+        for a in above[c]:
+            pending[a] -= 1
+            if pending[a] == 0:
+                ready.append(a)
+    out.append(paint(color.DIM, LEGEND))
+    return out

git_nearest/refs.py

@@ -0,0 +1,40 @@
+"""Rank remote refs by how close they are to HEAD."""
+from collections import namedtuple
+
+from .gitutil import git
+
+REMOTES = "refs/remotes/"
+
+Row = namedtuple("Row", "ahead behind ref")  # ref is the short name, e.g. origin/main
+
+
+def _counts_native():
+    """One git call for every ref; needs git >= 2.41 (%(ahead-behind:...))."""
+    out = git("for-each-ref", "--format=%(ahead-behind:HEAD)%09%(refname)", REMOTES, check=False)
+    if not out:
+        return None
+    return [line.split("\t") for line in out.splitlines()]
+
+
+def _counts_fallback():
+    """One rev-list per ref, for older git."""
+    names = git("for-each-ref", "--format=%(refname)", REMOTES).splitlines()
+    pairs = []
+    for name in names:
+        if not name.endswith("/HEAD"):
+            pairs.append((git("rev-list", "--left-right", "--count", name + "...HEAD"), name))
+    return pairs
+
+
+def rank(limit, native=True):
+    """Closest remote refs first: fewest commits HEAD is ahead by, then fewest it is behind by."""
+    pairs = (_counts_native() if native else None) or _counts_fallback()
+    rows = []
+    for counts, name in pairs:
+        if name.endswith("/HEAD"):  # origin/HEAD is just a pointer
+            continue
+        # "<only in ref = behind> <only in HEAD = ahead>"
+        behind, ahead = counts.split()
+        rows.append(Row(int(ahead), int(behind), name[len(REMOTES):]))
+    rows.sort(key=lambda r: (r.ahead, r.behind, r.ref))
+    return rows[:limit]

git_nearest/status.py

@@ -0,0 +1,31 @@
+"""Working tree state of HEAD: is it clean, and if not, how dirty."""
+from collections import namedtuple
+
+from . import color
+from .gitutil import git
+
+Counts = namedtuple("Counts", "staged modified untracked conflicted")
+
+
+def read():
+    counts = dict(staged=0, modified=0, untracked=0, conflicted=0)
+    for line in git("status", "--porcelain=v1", strip=False).splitlines():
+        x, y = line[0], line[1]
+        if x == "!":
+            continue
+        if x == "?":
+            counts["untracked"] += 1
+        elif "U" in (x, y) or (x, y) in (("A", "A"), ("D", "D")):
+            counts["conflicted"] += 1
+        else:
+            counts["staged"] += x != " "
+            counts["modified"] += y != " "
+    return Counts(**counts)
+
+
+def describe(counts, paint):
+    """'[clean]' or e.g. '[2 staged, 3 modified, 1 untracked]'."""
+    parts = ["%d %s" % (n, name) for name, n in counts._asdict().items() if n]
+    if not parts:
+        return paint(color.GREEN, "[clean]")
+    return paint(color.RED if counts.conflicted else color.YELLOW, "[%s]" % ", ".join(parts))

git_nearest/table.py

@@ -0,0 +1,19 @@
+"""The default output: one line per ref with ahead/behind and the merge-base."""
+from . import color
+from .gitutil import git
+
+
+def render(rows, paint, head_line=None):
+    ups = ["↑%d" % r.ahead for r in rows]
+    downs = ["↓%d" % r.behind for r in rows]
+    wa, wb, wn = max(map(len, ups)), max(map(len, downs)), max(len(r.ref) for r in rows)
+    lines = [head_line] if head_line else []
+    for r, up, down in zip(rows, ups, downs):
+        base = git("merge-base", "refs/remotes/" + r.ref, "HEAD", check=False)[:8]
+        lines.append("%s %s  %s  %s" % (
+            paint(color.GREEN, up.ljust(wa)),
+            paint(color.RED, down.ljust(wb)),
+            r.ref.ljust(wn),
+            paint(color.DIM, base),
+        ))
+    return lines

git_nearest-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: git-nearest
+Version: 0.1.0
+Summary: Find the remote branches closest to your current branch, with ahead/behind counts and a compact jj-style graph.
+Project-URL: Homepage, https://github.com/hwei/git-nearest
+Project-URL: Issues, https://github.com/hwei/git-nearest/issues
+Author-email: hwei <814065+hwei@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: branch,cli,git,merge-base,parent-branch
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# git-nearest
+
+Which remote branch is my current branch closest to?
+
+```console
+$ git nearest
+@  HEAD -> fix-typo  [1 staged, 1 untracked]
+↑2 ↓0  origin/main           574e9395
+↑8 ↓0  origin/feature/login  51eef8f5
+↑9 ↓1  origin/release/1.2    fc1afa3b
+```
+
+The first line shows where HEAD is and the state of the working tree: `[clean]`, or counts such as
+`[2 staged, 3 modified, 1 untracked]` (conflicted files turn it red). That is the thing to check
+before moving the branch somewhere else.
+
+`↑` is how many commits HEAD has that the remote branch doesn't, `↓` is how many the remote branch
+has that HEAD doesn't, and the last column is the merge-base. The closest branch (fewest `↑`, then
+fewest `↓`) comes first. Remote branches with the same tip all show up, so you can see ties
+instead of having one picked for you.
+
+## Graph
+
+`git nearest -g` draws how HEAD and those branches relate, in the style of
+[`jj log`](https://docs.jj-vcs.dev/): newest on top, and runs of ordinary commits folded into a
+`~  (n)` row on the vertical line.
+
+```console
+$ git nearest -g
+@  ae22273d  HEAD -> fix-typo  [1 staged, 1 untracked]
+~  (1)
+○  574e9395  origin/main
+├─╮
+~ │  (3)
+│ ○  51eef8f5  origin/feature/login
+│ ~  (2)
+│ │ ○  2cf4c0c2  origin/release/1.2
+├─┼─╯
+○ │  fc1afa3b  merge-base
+~ │  (1)
+├─╯
+○  5a42fea0  merge-base
+~ (n) = n commits folded between
+```
+
+Only HEAD, the branch tips and the merge-bases between them are drawn. `(3)` means three commits sit
+between the nodes above and below it.
+
+Both examples are real output from a synthetic repository built by
+[`scripts/demo.py`](https://github.com/hwei/git-nearest/blob/main/scripts/demo.py).
+
+## Install
+
+Needs Python 3.8+ and git. No other dependencies.
+
+```console
+uv tool install git-nearest      # or: pipx install git-nearest
+```
+
+The package installs an executable called `git-nearest`; git runs any `git-<name>` on your `PATH` as
+`git <name>`.
+
+## Usage
+
+```
+git nearest [N] [-g] [--no-status] [--color {auto,always,never}] [--no-color]
+```
+
+| | |
+|---|---|
+| `N` | how many branches to show (default 5) |
+| `-g`, `--graph` | draw the graph instead of the table |
+| `--no-status` | skip the working tree check (it runs `git status`, which can be slow on huge repositories) |
+| `--color` | `auto` (default) colors only on a terminal and respects `NO_COLOR` |
+
+## How it works
+
+git has no notion of a branch's "parent", only of common ancestors, so this is a heuristic, not a
+lookup. For every ref under `refs/remotes` it asks git for the ahead/behind counts against HEAD in a
+single `for-each-ref --format='%(ahead-behind:HEAD)'` call (git 2.41+; older versions fall back to one
+`rev-list` per ref, which is slower on repositories with many branches).
+
+The graph walks the history above the common base once, marks which tips can reach each commit, and
+keeps only the commits where those sets change. Those are the merge-bases.
+
+## Limitations
+
+- "Nearest" is by commit count. If you branched from `main` last week and `release/1.0` happens to be
+  two commits behind `main`, `release/1.0` is nearer. Look at the graph when it matters.
+- Branches that are not in `refs/remotes` are ignored. Run `git fetch` first.
+- Folded counts on a node with two parents are the commits unique to that node, shown once.
+
+## Similar tools
+
+- Scripts based on `git show-branch` or on grepping `git log --decorate` for `origin/` (the usual
+  Stack Overflow answers) look only at the first decorated ancestor, so they miss ties and give no
+  distance.
+- [Git Town](https://www.git-town.com/) records a parent for each branch when it creates the branch.
+  That is exact but only works for branches it knows about; `git-nearest` infers from history and needs
+  no setup.
+
+## Development
+
+```console
+uv run pytest
+```
+
+## License
+
+MIT

git_nearest-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+git_nearest/__init__.py,sha256=T4bDFCMF22YiEOc93D53WE-XGn-VsNiY2FfTEh2iOC8,71
+git_nearest/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+git_nearest/cli.py,sha256=aCOIFDjWFZPFsxdaJgxmIPgmXFqpjo_e7dcp97sVaqU,2566
+git_nearest/color.py,sha256=2dFNZECboq2fU2hII0E2a48uGVmwL0pSFD_0bY7W5kU,359
+git_nearest/gitutil.py,sha256=fHjnG0JdiRK0WcJkHZ0GJ7X3xAdbCn7wKWCjJ5cJ4_U,705
+git_nearest/graph.py,sha256=XCHILZimX3vVcKoGuuXeEZPEwN-J3pcGqsOZ7_Vjf6A,6221
+git_nearest/refs.py,sha256=FVTqehUsIbKXemodUBK4FaMZUfvWhbvRQoM98t2u6vk,1451
+git_nearest/status.py,sha256=QrpLDED4TCeIXV-m75KVEB5fbpgVwGBVrVU1yZzdQSI,1074
+git_nearest/table.py,sha256=VeVs-Hm52qUhXwHqDCIH5F2rKoGR09YLuqoOaVHLMkQ,749
+git_nearest-0.1.0.dist-info/METADATA,sha256=RgahOC7xLdRFS4QmCE-3ATgWhUilotcn1j_KhitIBYA,4594
+git_nearest-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+git_nearest-0.1.0.dist-info/entry_points.txt,sha256=CzRI0mP0b4MM41-_fu1Rww5bqupwt43qNUGAMsg4kpE,53
+git_nearest-0.1.0.dist-info/licenses/LICENSE,sha256=KCGRMaq5ZibfutyPc2GJRMNoB4QoR4YiPrrgHFGPsE4,1061
+git_nearest-0.1.0.dist-info/RECORD,,

git_nearest-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

git_nearest-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-nearest = git_nearest.cli:main

git_nearest-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hwei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.