git-nearest 0.1.0__tar.gz

git_nearest-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+uv.lock

git_nearest-0.1.0/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.

git_nearest-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,110 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "git-nearest"
+version = "0.1.0"
+description = "Find the remote branches closest to your current branch, with ahead/behind counts and a compact jj-style graph."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [{ name = "hwei", email = "814065+hwei@users.noreply.github.com" }]
+keywords = ["git", "branch", "cli", "merge-base", "parent-branch"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/hwei/git-nearest"
+Issues = "https://github.com/hwei/git-nearest/issues"
+
+# An executable named git-<name> on PATH is run by `git <name>`.
+[project.scripts]
+git-nearest = "git_nearest.cli:main"
+
+[dependency-groups]
+dev = ["pytest"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/git_nearest"]
+
+# Allowlist: hatch ignores .git/info/exclude, so local-only files would otherwise ship.
+[tool.hatch.build.targets.sdist]
+include = ["src/git_nearest", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

git_nearest-0.1.0/src/git_nearest/__init__.py

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

git_nearest-0.1.0/src/git_nearest/__main__.py

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

git_nearest-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/conftest.py

@@ -0,0 +1,64 @@
+import os
+import subprocess
+
+import pytest
+
+ENV = {
+    "GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@example.com",
+    "GIT_COMMITTER_NAME": "t", "GIT_COMMITTER_EMAIL": "t@example.com",
+    "GIT_CONFIG_GLOBAL": os.devnull, "GIT_CONFIG_SYSTEM": os.devnull,
+}
+
+
+class Repo:
+    def __init__(self, path):
+        self.path = str(path)
+        self.count = 0  # unique messages: identical parent/tree/message/second would give identical commits
+
+    def git(self, *args):
+        p = subprocess.run(
+            ["git", *args], cwd=self.path, env={**os.environ, **ENV},
+            capture_output=True, text=True, check=True,
+        )
+        return p.stdout.strip()
+
+    def commit(self, n=1):
+        for _ in range(n):
+            self.count += 1
+            self.git("commit", "-q", "--allow-empty", "-m", "c%d" % self.count)
+
+    def remote(self, name, rev="HEAD"):
+        self.git("update-ref", "refs/remotes/" + name, self.git("rev-parse", rev))
+
+
+@pytest.fixture
+def repo(tmp_path, monkeypatch):
+    r = Repo(tmp_path)
+    r.git("init", "-q", "-b", "main")
+    monkeypatch.chdir(tmp_path)
+    for k, v in ENV.items():
+        monkeypatch.setenv(k, v)
+    return r
+
+
+@pytest.fixture
+def forked(repo):
+    """main and feat fork from a3; feat is merged into main; work branches off main.
+
+        work:  w1 w2
+        main:  a1 a2 a3 m1 m2 M(merge feat) m3 m4
+        feat:  a3 f1 f2 f3
+    """
+    repo.commit(3)
+    repo.git("checkout", "-q", "-b", "feat")
+    repo.commit(3)
+    repo.remote("origin/feat")
+    repo.git("checkout", "-q", "main")
+    repo.commit(2)
+    repo.remote("origin/main")
+    repo.git("merge", "-q", "--no-ff", "feat", "-m", "merge feat")
+    repo.commit(2)
+    repo.git("checkout", "-q", "-b", "work")
+    repo.commit(2)
+    repo.remote("origin/other", "main~1")
+    return repo

git_nearest-0.1.0/tests/test_cli.py

@@ -0,0 +1,81 @@
+import re
+
+import pytest
+
+from git_nearest import refs
+from git_nearest.cli import main
+
+
+def run(capsys, *argv):
+    code = main(["--color", "never", *argv])
+    out = capsys.readouterr()
+    return code, re.sub(r"\b[0-9a-f]{8}\b", "H", out.out), out.err
+
+
+def test_table_orders_by_ahead_then_behind(forked, capsys):
+    code, out, _ = run(capsys)
+    assert code == 0
+    assert out.splitlines() == [
+        "@  HEAD -> work  [clean]",
+        "↑3 ↓0  origin/other  H",
+        "↑7 ↓0  origin/feat   H",
+        "↑8 ↓0  origin/main   H",
+    ]
+
+
+def test_limit(forked, capsys):
+    _, out, _ = run(capsys, "1")
+    assert out.splitlines() == ["@  HEAD -> work  [clean]", "↑3 ↓0  origin/other  H"]
+
+
+def test_behind_is_counted(repo, capsys):
+    repo.commit(2)
+    repo.git("checkout", "-q", "-b", "side")
+    repo.commit(2)
+    repo.git("checkout", "-q", "main")
+    repo.commit(1)
+    repo.remote("origin/main")
+    repo.git("checkout", "-q", "side")
+    _, out, _ = run(capsys)
+    assert out.splitlines()[1] == "↑2 ↓1  origin/main  H"
+
+
+def test_fallback_matches_native(forked):
+    assert refs.rank(10, native=False) == refs.rank(10, native=True)
+
+
+def test_origin_head_is_skipped(forked, capsys):
+    forked.git("symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/main")
+    _, out, _ = run(capsys, "--no-status")
+    assert "HEAD" not in out
+
+
+def test_no_remote_refs(repo, capsys):
+    repo.commit()
+    code, _, err = run(capsys)
+    assert code == 1
+    assert "no remote branches" in err
+
+
+def test_no_commits(repo, capsys):
+    code, _, err = run(capsys)
+    assert code == 1
+    assert err.startswith("git-nearest:")
+
+
+def test_not_a_repo(tmp_path, monkeypatch, capsys):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("GIT_CEILING_DIRECTORIES", str(tmp_path.parent))
+    code, _, err = run(capsys)
+    assert code == 1
+    assert "not a git repository" in err
+
+
+def test_bad_limit(forked):
+    with pytest.raises(SystemExit):
+        main(["0"])
+
+
+def test_color_always_emits_escapes(forked, capsys):
+    main(["--color", "always"])
+    assert "\033[" in capsys.readouterr().out

git_nearest-0.1.0/tests/test_graph.py

@@ -0,0 +1,72 @@
+import re
+
+from git_nearest.cli import main
+
+
+def graph(capsys, *argv):
+    main(["--color", "never", "-g", *argv])
+    return re.sub(r"\b[0-9a-f]{8}\b", "H", capsys.readouterr().out).splitlines()
+
+
+def test_merge_and_fork(forked, capsys):
+    assert graph(capsys) == [
+        "@  H  HEAD -> work  [clean]",
+        "~  (2)",
+        "○  H  origin/other",
+        "├─╮",
+        "~ │  (1)",
+        "○ │  H  origin/feat",
+        "~ │  (2)",
+        "│ ○  H  origin/main",
+        "│ ~  (1)",
+        "├─╯",
+        "○  H  merge-base",
+        "~ (n) = n commits folded between",
+    ]
+
+
+def test_linear_history_has_no_lanes(repo, capsys):
+    repo.commit(3)
+    repo.remote("origin/main")
+    repo.commit(4)
+    assert graph(capsys) == [
+        "@  H  HEAD -> main  [clean]",
+        "~  (3)",
+        "○  H  origin/main",
+        "~ (n) = n commits folded between",
+    ]
+
+
+def test_head_on_a_remote_tip_shares_a_node(repo, capsys):
+    repo.commit(2)
+    repo.remote("origin/main")
+    assert graph(capsys)[0] == "@  H  HEAD -> main, origin/main  [clean]"
+
+
+def test_adjacent_nodes_have_no_fold_row(repo, capsys):
+    repo.commit(1)
+    repo.remote("origin/main")
+    repo.commit(1)
+    assert graph(capsys) == [
+        "@  H  HEAD -> main  [clean]",
+        "○  H  origin/main",
+        "~ (n) = n commits folded between",
+    ]
+
+
+def test_detached_head(repo, capsys):
+    repo.commit(2)
+    repo.remote("origin/main")
+    repo.git("checkout", "-q", "--detach")
+    repo.commit(1)
+    assert graph(capsys)[0] == "@  H  HEAD (detached)  [clean]"
+
+
+def test_unrelated_histories_do_not_crash(repo, capsys):
+    repo.commit(2)
+    repo.git("checkout", "-q", "--orphan", "other")
+    repo.commit(2)
+    repo.remote("origin/main", "main")
+    lines = graph(capsys)
+    assert any("origin/main" in line for line in lines)
+    assert any("HEAD -> other" in line for line in lines)

git_nearest-0.1.0/tests/test_status.py

@@ -0,0 +1,93 @@
+import re
+
+from git_nearest import status
+from git_nearest.color import Painter
+from git_nearest.cli import main
+
+
+def head_line(capsys, *argv):
+    main(["--color", "never", *argv])
+    return capsys.readouterr().out.splitlines()[0]
+
+
+def write(repo, name, text="x"):
+    with open(repo.path + "/" + name, "w") as f:
+        f.write(text)
+
+
+def tracked(repo, name):
+    write(repo, name)
+    repo.git("add", name)
+    repo.git("commit", "-q", "-m", "add " + name)
+
+
+def test_clean(forked):
+    assert status.read() == status.Counts(0, 0, 0, 0)
+
+
+def test_counts_each_kind(forked):
+    tracked(forked, "a.txt")
+    tracked(forked, "b.txt")
+    write(forked, "a.txt", "changed")        # modified
+    write(forked, "b.txt", "changed")
+    forked.git("add", "b.txt")               # staged
+    write(forked, "new.txt")                 # untracked
+    assert status.read() == status.Counts(staged=1, modified=1, untracked=1, conflicted=0)
+
+
+def test_file_both_staged_and_modified_counts_in_both(forked):
+    tracked(forked, "a.txt")
+    write(forked, "a.txt", "one")
+    forked.git("add", "a.txt")
+    write(forked, "a.txt", "two")
+    assert status.read() == status.Counts(staged=1, modified=1, untracked=0, conflicted=0)
+
+
+def test_ignored_files_are_not_counted(forked):
+    tracked(forked, ".gitignore")
+    write(forked, ".gitignore", "*.log\n")
+    forked.git("add", ".gitignore")
+    forked.git("commit", "-q", "-m", "ignore")
+    write(forked, "x.log")
+    assert status.read() == status.Counts(0, 0, 0, 0)
+
+
+def test_conflict(repo):
+    tracked(repo, "f.txt")
+    repo.git("checkout", "-q", "-b", "side")
+    write(repo, "f.txt", "side")
+    repo.git("commit", "-qam", "side")
+    repo.git("checkout", "-q", "main")
+    write(repo, "f.txt", "main")
+    repo.git("commit", "-qam", "main")
+    try:
+        repo.git("merge", "side")
+    except Exception:
+        pass
+    assert status.read().conflicted == 1
+
+
+def test_header_line_in_table(forked, capsys):
+    tracked(forked, "a.txt")
+    write(forked, "a.txt", "changed")
+    write(forked, "new.txt")
+    assert head_line(capsys) == "@  HEAD -> work  [1 modified, 1 untracked]"
+
+
+def test_graph_marks_head_node(forked, capsys):
+    write(forked, "new.txt")
+    main(["--color", "never", "-g"])
+    first = capsys.readouterr().out.splitlines()[0]
+    assert re.sub(r"\b[0-9a-f]{8}\b", "H", first) == "@  H  HEAD -> work  [1 untracked]"
+
+
+def test_no_status_skips_it(forked, capsys):
+    main(["--color", "never", "--no-status"])
+    assert capsys.readouterr().out.splitlines()[0].startswith("↑")
+
+
+def test_describe_colors():
+    p = Painter(True)
+    assert "\033[32m[clean]" in status.describe(status.Counts(0, 0, 0, 0), p)
+    assert "\033[33m" in status.describe(status.Counts(0, 1, 0, 0), p)
+    assert "\033[31m" in status.describe(status.Counts(0, 0, 0, 1), p)