git-nearest 0.1.0__tar.gz → 0.2.0__tar.gz

{git_nearest-0.1.0 → git_nearest-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-nearest
-Version: 0.1.0
+Version: 0.2.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
@@ -40,7 +40,7 @@ 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
+[`jj log`](https://docs.jj-vcs.dev/): newest on top (by commit date, parents never above their children), and runs of ordinary commits folded into a
 `~  (n)` row on the vertical line.
 
 ```console
@@ -50,12 +50,12 @@ $ git nearest -g
 ○  574e9395  origin/main
 ├─╮
 ~ │  (3)
-│ ○  51eef8f5  origin/feature/login
-│ ~  (2)
 │ │ ○  2cf4c0c2  origin/release/1.2
 ├─┼─╯
 ○ │  fc1afa3b  merge-base
 ~ │  (1)
+│ ○  51eef8f5  origin/feature/login
+│ ~  (2)
 ├─╯
 ○  5a42fea0  merge-base
 ~ (n) = n commits folded between
@@ -81,15 +81,17 @@ The package installs an executable called `git-nearest`; git runs any `git-<name
 ## Usage
 
 ```
-git nearest [N] [-g] [--no-status] [--color {auto,always,never}] [--no-color]
+git nearest [N] [-b REV] [-g] [--no-status] [--color {auto,always,never}] [--no-color] [--version]
 ```
 
 | | |
 |---|---|
 | `N` | how many branches to show (default 5) |
+| `-b`, `--branch REV` | measure from this branch or commit instead of HEAD; skips the working tree check, which only describes HEAD |
 | `-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` |
+| `--version` | print the version and exit |
 
 ## How it works
 

{git_nearest-0.1.0 → git_nearest-0.2.0}/README.md

@@ -22,7 +22,7 @@ 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
+[`jj log`](https://docs.jj-vcs.dev/): newest on top (by commit date, parents never above their children), and runs of ordinary commits folded into a
 `~  (n)` row on the vertical line.
 
 ```console
@@ -32,12 +32,12 @@ $ git nearest -g
 ○  574e9395  origin/main
 ├─╮
 ~ │  (3)
-│ ○  51eef8f5  origin/feature/login
-│ ~  (2)
 │ │ ○  2cf4c0c2  origin/release/1.2
 ├─┼─╯
 ○ │  fc1afa3b  merge-base
 ~ │  (1)
+│ ○  51eef8f5  origin/feature/login
+│ ~  (2)
 ├─╯
 ○  5a42fea0  merge-base
 ~ (n) = n commits folded between
@@ -63,15 +63,17 @@ The package installs an executable called `git-nearest`; git runs any `git-<name
 ## Usage
 
 ```
-git nearest [N] [-g] [--no-status] [--color {auto,always,never}] [--no-color]
+git nearest [N] [-b REV] [-g] [--no-status] [--color {auto,always,never}] [--no-color] [--version]
 ```
 
 | | |
 |---|---|
 | `N` | how many branches to show (default 5) |
+| `-b`, `--branch REV` | measure from this branch or commit instead of HEAD; skips the working tree check, which only describes HEAD |
 | `-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` |
+| `--version` | print the version and exit |
 
 ## How it works
 

{git_nearest-0.1.0 → git_nearest-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "git-nearest"
-version = "0.1.0"
+version = "0.2.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" }

{git_nearest-0.1.0 → git_nearest-0.2.0}/src/git_nearest/__init__.py

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

{git_nearest-0.1.0 → git_nearest-0.2.0}/src/git_nearest/cli.py

@@ -13,6 +13,8 @@ def _parser():
         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("-b", "--branch", metavar="REV", default="HEAD",
+                   help="measure from this branch or commit instead of HEAD (skips the working tree check)")
     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")
@@ -21,13 +23,18 @@ def _parser():
     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
+def head_label(rev):
+    """How to name the commit we measure from: "HEAD -> main", "HEAD (detached)", or REV as typed."""
+    if rev != "HEAD":
+        return rev
     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)
+    return "HEAD -> " + branch if branch else "HEAD (detached)"
+
+
+def head_line(label, note, paint):
+    """The line above the table: what we measure from and whether the working tree is clean."""
+    line = "%s  %s" % (paint(color.GREEN_BOLD, "@"), paint(color.GREEN_BOLD, label))
+    return line + "  " + note if note else line
 
 
 def _use_color(mode):
@@ -46,17 +53,23 @@ def main(argv=None):
         sys.stdout.reconfigure(encoding="utf-8")
 
     try:
-        git("rev-parse", "--verify", "-q", "HEAD")
-        rows = refs.rank(args.limit)
+        base = git("rev-parse", "--verify", "-q", args.branch + "^{commit}", check=args.branch == "HEAD")
+        if not base:
+            raise GitError("not a valid branch or commit: " + args.branch)
+        skip = git("rev-parse", "--symbolic-full-name", args.branch, check=False)
+        rows = refs.rank(args.limit, base, skip)
         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)
+        # the working tree belongs to HEAD, so it says nothing about another branch
+        checks_tree = args.branch == "HEAD" and not args.no_status
+        note = status.describe(status.read(), paint) if checks_tree else None
+        label = head_label(args.branch)
         if args.graph:
-            lines = graph.render([r.ref for r in rows], paint, note)
+            lines = graph.render([r.ref for r in rows], paint, base, label, note)
         else:
-            lines = table.render(rows, paint, head_line(note, paint))
+            lines = table.render(rows, paint, base, head_line(label, note, paint) if note or args.branch != "HEAD" else None)
     except GitError as e:
         print("git-nearest: " + str(e), file=sys.stderr)
         return 1

{git_nearest-0.1.0 → git_nearest-0.2.0}/src/git_nearest/graph.py

@@ -10,9 +10,8 @@ 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)
+def render(refs, paint, head, label, head_note=None):
+    """head: the commit everything is measured from; label: how to name it (e.g. "HEAD -> main")."""
     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):
@@ -56,8 +55,14 @@ def render(refs, paint, head_note=None):
     def on_head_line(c):
         return c == head or bool(allanc[head] & node_bit[c]) or bool(allanc[c] & node_bit[head])
 
+    # Newest first among the nodes that are ready to draw; children still always come before parents.
+    when = {}
+    for line in git("show", "-s", "--format=%H %ct", *nodes).splitlines():
+        sha, ts = line.split()
+        when[sha] = int(ts)
+
     def sort_key(c):
-        return (not on_head_line(c), sorted(names.get(c, [c]))[0])
+        return (-when[c], 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
@@ -75,7 +80,7 @@ def render(refs, paint, head_note=None):
     def node_text(c):
         parts = []
         if c == head:
-            parts.append(paint(color.GREEN_BOLD, "HEAD -> " + branch if branch else "HEAD (detached)"))
+            parts.append(paint(color.GREEN_BOLD, label))
         parts += [paint(color.CYAN, n) for n in sorted(names.get(c, []))]
         if not parts:
             parts.append(paint(color.DIM, "merge-base"))
@@ -136,7 +141,7 @@ def render(refs, paint, head_note=None):
                 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]))
+            emit({k: "~"}, text=paint(color.DIM, "(%d)" % folded[c]))
 
     pending = {c: 0 for c in nodes}
     for c in nodes:

{git_nearest-0.1.0 → git_nearest-0.2.0}/src/git_nearest/refs.py

@@ -8,32 +8,35 @@ REMOTES = "refs/remotes/"
 Row = namedtuple("Row", "ahead behind ref")  # ref is the short name, e.g. origin/main
 
 
-def _counts_native():
+def _counts_native(base):
     """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)
+    out = git("for-each-ref", "--format=%(ahead-behind:" + base + ")%09%(refname)", REMOTES, check=False)
     if not out:
         return None
     return [line.split("\t") for line in out.splitlines()]
 
 
-def _counts_fallback():
+def _counts_fallback(base):
     """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))
+            pairs.append((git("rev-list", "--left-right", "--count", name + "..." + base), 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()
+def rank(limit, base="HEAD", skip=None, native=True):
+    """Closest remote refs first: fewest commits base is ahead by, then fewest it is behind by.
+
+    skip is a full refname to leave out (the ref we are measuring from).
+    """
+    pairs = (_counts_native(base) if native else None) or _counts_fallback(base)
     rows = []
     for counts, name in pairs:
-        if name.endswith("/HEAD"):  # origin/HEAD is just a pointer
+        if name == skip or name.endswith("/HEAD"):  # origin/HEAD is just a pointer
             continue
-        # "<only in ref = behind> <only in HEAD = ahead>"
+        # "<only in ref = behind> <only in base = 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))

{git_nearest-0.1.0 → git_nearest-0.2.0}/src/git_nearest/table.py

@@ -3,13 +3,13 @@ from . import color
 from .gitutil import git
 
 
-def render(rows, paint, head_line=None):
+def render(rows, paint, base, 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]
+        base = git("merge-base", "refs/remotes/" + r.ref, base, check=False)[:8]
         lines.append("%s %s  %s  %s" % (
             paint(color.GREEN, up.ljust(wa)),
             paint(color.RED, down.ljust(wb)),

{git_nearest-0.1.0 → git_nearest-0.2.0}/tests/test_cli.py

@@ -79,3 +79,30 @@ def test_bad_limit(forked):
 def test_color_always_emits_escapes(forked, capsys):
     main(["--color", "always"])
     assert "\033[" in capsys.readouterr().out
+
+
+def test_branch_measures_from_another_rev(forked, capsys):
+    _, out, _ = run(capsys, "-b", "main")
+    assert out.splitlines() == [
+        "@  main",
+        "↑1 ↓0  origin/other  H",
+        "↑5 ↓0  origin/feat   H",
+        "↑6 ↓0  origin/main   H",
+    ]
+
+
+def test_branch_skips_itself_when_remote(forked, capsys):
+    _, out, _ = run(capsys, "-b", "origin/other")
+    assert "origin/other" not in out.splitlines()[1]
+    assert out.splitlines()[0] == "@  origin/other"
+
+
+def test_branch_graph_is_labelled(forked, capsys):
+    _, out, _ = run(capsys, "-g", "-b", "feat")
+    assert any(l.startswith("@") and l.endswith("H  feat, origin/feat") for l in out.splitlines())
+
+
+def test_bad_branch(forked, capsys):
+    code, _, err = run(capsys, "-b", "nope")
+    assert code == 1
+    assert "nope" in err

{git_nearest-0.1.0 → git_nearest-0.2.0}/tests/test_graph.py

@@ -70,3 +70,21 @@ def test_unrelated_histories_do_not_crash(repo, capsys):
     lines = graph(capsys)
     assert any("origin/main" in line for line in lines)
     assert any("HEAD -> other" in line for line in lines)
+
+
+def test_newest_first_among_branches(repo, capsys, monkeypatch):
+    def commit_at(ts):
+        monkeypatch.setenv("GIT_COMMITTER_DATE", "%d +0000" % ts)
+        repo.commit()
+
+    commit_at(1000000000)
+    repo.git("checkout", "-q", "-b", "side")
+    commit_at(1000000100)
+    repo.remote("origin/a-old")  # sorts first by name but is older
+    repo.git("checkout", "-q", "main")
+    commit_at(1000000200)
+    repo.remote("origin/z-new")
+    commit_at(1000000300)
+    lines = graph(capsys)
+    refs = [l for l in lines if "origin/" in l]
+    assert [l.split()[-1] for l in refs] == ["origin/z-new", "origin/a-old"]