git-merge-list 0.0.1__py3-none-any.whl

git_merge_list/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Junbo Zheng
+"""git-merge-list: list commits merged within a time range across git repos."""
+
+__version__ = "0.0.1"

git_merge_list/cli.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Junbo Zheng
+"""CLI entry point for git-merge-list."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime
+from importlib.metadata import PackageNotFoundError, version
+
+from . import __version__
+from .discover import find_repos
+from .gerrit import derive_base, get_remote_url
+from .output import print_terminal, render_markdown
+from .query import query_repo
+from .timeparse import build_range
+
+PKG = "git-merge-list"
+
+
+def _version() -> str:
+    try:
+        return version(PKG)
+    except PackageNotFoundError:
+        return __version__
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="git-merge-list",
+        description=(
+            "Recursively scan git repos under a path and list commits merged "
+            "within a time range (by committer date), with Gerrit patch links."
+        ),
+    )
+    p.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="root path to scan for git repos (default: current directory)",
+    )
+    time_grp = p.add_argument_group("time selector (pick one)")
+    time_grp.add_argument("--day", help="YYYY-MM-DD — the whole calendar day")
+    time_grp.add_argument("--hour", help="'YYYY-MM-DD HH' — the whole calendar hour")
+    time_grp.add_argument(
+        "--since",
+        help="start time (inclusive), e.g. '2026-07-05' or " "'2026-07-05 14:00'",
+    )
+    time_grp.add_argument(
+        "--until",
+        help="end time (exclusive-ish, inclusive in git). "
+        "Defaults to now when only --since is given.",
+    )
+    p.add_argument(
+        "--tz",
+        help="timezone for the selectors: '+0800', '+08:00', 'Z', or an "
+        "IANA name like 'Asia/Shanghai'. Defaults to system local.",
+    )
+    p.add_argument(
+        "--author",
+        help="regex matched against author name/email (the 'submitter'). "
+        "Use --by-committer to match committer instead.",
+    )
+    p.add_argument(
+        "--by-committer",
+        action="store_true",
+        help="show committer (not author) as the 'submitter' column. In "
+        "Gerrit flows the author is usually the developer; the committer "
+        "is often the merge bot.",
+    )
+    p.add_argument("--max-count", type=int, help="per-repo commit cap")
+    p.add_argument(
+        "--reverse", action="store_true", help="oldest-first within each repo"
+    )
+    p.add_argument(
+        "-o",
+        "--output",
+        help="Markdown report path. Defaults to "
+        "git-merge-list-report-<timestamp>.md. Use with --no-markdown to "
+        "suppress the file entirely.",
+    )
+    p.add_argument(
+        "--no-markdown",
+        action="store_true",
+        help="do not write a Markdown report file",
+    )
+    p.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"{PKG} {_version()}",
+    )
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    try:
+        since, until = build_range(
+            day=args.day,
+            hour=args.hour,
+            since=args.since,
+            until=args.until,
+            tz_arg=args.tz,
+        )
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    repos = find_repos(args.path)
+    if not repos:
+        print(f"no git repos found under {args.path}", file=sys.stderr)
+        return 1
+
+    grouped: list[tuple[str, list]] = []
+    total = 0
+    for repo in repos:
+        base = derive_base(get_remote_url(repo))
+        commits, err = query_repo(
+            repo,
+            since,
+            until,
+            author=args.author,
+            max_count=args.max_count,
+            reverse=args.reverse,
+            base_url=base,
+        )
+        if err:
+            print(f"warn: {repo}: {err}", file=sys.stderr)
+        if commits:
+            grouped.append((repo, commits))
+            total += len(commits)
+
+    print_terminal(
+        grouped,
+        by_committer=args.by_committer,
+        since=since,
+        until=until,
+    )
+
+    if not args.no_markdown:
+        out_path = args.output or (
+            f"git-merge-list-report-" f"{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
+        )
+        md = render_markdown(
+            grouped,
+            by_committer=args.by_committer,
+            since=since,
+            until=until,
+            root=args.path,
+        )
+        with open(out_path, "w", encoding="utf-8") as f:
+            f.write(md)
+        print(f"report: {out_path}", file=sys.stderr)
+
+    return 0 if total > 0 else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

git_merge_list/discover.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Junbo Zheng
+"""Recursively discover git repos under a path.
+
+A "repo" is any directory that contains a `.git` entry — either a `.git`
+directory (normal checkout) or a `.git` file (worktree / submodule). This
+covers both standalone repos and the many individual git repos created by
+the `repo` tool, since each checked-out project is itself a normal git repo.
+
+We never descend into `.git` directories or the `.repo/` metadata directory,
+but we DO keep walking a found repo's subdirectories so nested submodules
+are picked up too.
+"""
+
+from __future__ import annotations
+
+import os
+
+# Directory names we never recurse into.
+SKIP_DIR_NAMES = {".git", ".repo"}
+
+
+def find_repos(root: str) -> list[str]:
+    """Return repo-root paths under `root`, in walk order, deduplicated."""
+    repos: list[str] = []
+    seen: set[str] = set()
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Detect BEFORE pruning: .git is itself in SKIP_DIR_NAMES, so if we
+        # pruned first the membership check below would always be False.
+        is_repo = ".git" in dirnames or ".git" in filenames
+        # Prune the walk so we don't enter .git/.repo subtrees.
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIR_NAMES]
+        if is_repo and dirpath not in seen:
+            seen.add(dirpath)
+            repos.append(dirpath)
+    return repos

git_merge_list/gerrit.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Junbo Zheng
+"""Derive a Gerrit patch URL from a repo's remote URL + a commit's Change-Id.
+
+The remote URL gives us the Gerrit host; the commit message's `Change-Id`
+gives us a searchable token. We build `https://<host>/q/<Change-Id>`, which
+is Gerrit's search-redirect URL — clickable, no network/auth needed at query
+time. When a commit has no Change-Id we fall back to the commit hash, which
+Gerrit can also search on.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from urllib.parse import urlparse
+
+# scp-like syntax: [user@]host:path  (no scheme)
+_SCP_RE = re.compile(r"^(?:[^@/\s]+@)?([^:/\s]+):")
+
+
+def derive_base(remote_url: str) -> str | None:
+    """Return `https://<host>[:port]` for a Gerrit remote URL, or None."""
+    s = (remote_url or "").strip()
+    if not s:
+        return None
+    if s.startswith(("ssh://", "http://", "https://")):
+        parsed = urlparse(s)
+        host = parsed.hostname
+        if not host:
+            return None
+        netloc = host
+        port = parsed.port
+        # The ssh port (e.g. Gerrit's 29418) is for `git push`, not web
+        # browsing — the Gerrit web UI runs on https (443). So for ssh
+        # remotes we drop the port entirely. Only an https/http remote with
+        # a non-default port could be a web UI on a custom port, so keep it.
+        if parsed.scheme in ("https", "http"):
+            default = 443 if parsed.scheme == "https" else 80
+            if port and port != default:
+                netloc = f"{host}:{port}"
+        scheme = "https" if parsed.scheme in ("ssh", "https") else "http"
+        return f"{scheme}://{netloc}"
+    m = _SCP_RE.match(s)
+    if m:
+        return f"https://{m.group(1)}"
+    return None
+
+
+def get_remote_url(repo: str) -> str:
+    """Return the origin (or first listed) remote URL for `repo`, or ''."""
+    try:
+        r = subprocess.run(
+            ["git", "-C", repo, "remote"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return ""
+    remotes = r.stdout.split()
+    if not remotes:
+        return ""
+    name = "origin" if "origin" in remotes else remotes[0]
+    r2 = subprocess.run(
+        ["git", "-C", repo, "remote", "get-url", name],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return r2.stdout.strip()
+
+
+def patch_url(base: str | None, change_id: str, commit_hash: str) -> str:
+    """Build a Gerrit search URL for the change, falling back to the hash."""
+    if not base:
+        return ""
+    token = change_id or commit_hash
+    if not token:
+        return ""
+    return f"{base}/q/{token}"

git_merge_list/output.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Junbo Zheng
+"""Render query results: a colored terminal table + a Markdown report file.
+
+Terminal coloring is gated on `stdout.isatty()` and the NO_COLOR convention
+(https://no-color.org). When color is off, output is plain text that still
+reads correctly — color is never the only signal.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from datetime import datetime
+
+from .query import Commit
+
+# Column width caps (terminal table only).
+W_PERSON = 18
+W_TIME = 25
+W_PATCH = 48
+W_SUBJECT = 50
+
+HEADER = ["Merge time", "Patch", "Submitter", "Subject"]
+
+
+def _color_enabled() -> bool:
+    if "NO_COLOR" in os.environ:
+        return False
+    return sys.stdout.isatty()
+
+
+def _c(text: str, code: str, enabled: bool) -> str:
+    return f"\033[{code}m{text}\033[0m" if enabled else text
+
+
+def _trunc(s: str, width: int) -> str:
+    return s if len(s) <= width else s[: width - 1] + "…"
+
+
+def _person(c: Commit, by_committer: bool) -> str:
+    name = c.committer_name if by_committer else c.author_name
+    email = c.committer_email if by_committer else c.author_email
+    return f"{name} <{email}>"
+
+
+def _patch_label(c: Commit) -> str:
+    # Short token for the patch link: prefer Change-Id, fall back to commit hash.
+    # The full token is already carried in the URL (https://<host>/q/<token>),
+    # so the link text only needs a short identifier.
+    if c.change_id:
+        return c.change_id[:11]
+    if c.patch_url:
+        return c.hash[:11]
+    return ""
+
+
+def print_terminal(
+    grouped: list[tuple[str, list[Commit]]],
+    *,
+    by_committer: bool,
+    since: str | None,
+    until: str | None,
+) -> None:
+    enabled = _color_enabled()
+    rng = until if until else "now"
+    print(_c("git-merge-list", "1;36", enabled) + f"  range: {since} .. {rng}")
+    total = sum(len(cs) for _, cs in grouped)
+    print(f"{total} commit(s) across {len(grouped)} repo(s)\n")
+
+    for repo, commits in grouped:
+        print(_c(repo, "1;33", enabled) + f"  ({len(commits)})")
+        rows = [
+            [
+                _trunc(c.committer_date, W_TIME),
+                _trunc(c.patch_url, W_PATCH),
+                _trunc(_person(c, by_committer), W_PERSON),
+                _trunc(c.subject, W_SUBJECT),
+            ]
+            for c in commits
+        ]
+        widths = [
+            max(len(h), max((len(r[i]) for r in rows), default=0))
+            for i, h in enumerate(HEADER)
+        ]
+        fmt = "  ".join(f"{{:<{w}}}" for w in widths)
+        print("  " + _c(fmt.format(*HEADER), "2", enabled))
+        for r in rows:
+            print("  " + fmt.format(*r))
+        print()
+
+
+def render_markdown(
+    grouped: list[tuple[str, list[Commit]]],
+    *,
+    by_committer: bool,
+    since: str | None,
+    until: str | None,
+    root: str,
+) -> str:
+    rng = until if until else "now"
+    total = sum(len(cs) for _, cs in grouped)
+    person_col = "Committer" if by_committer else "Author"
+    lines = [
+        "# git-merge-list report",
+        "",
+        f"- **Path**: `{root}`",
+        f"- **Range**: `{since}` .. `{rng}`",
+        f"- **Total**: {total} commit(s) across {len(grouped)} repo(s)",
+        f"- **Generated**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        "",
+    ]
+    if not grouped:
+        lines.append("_No commits in range._\n")
+        return "\n".join(lines)
+
+    for repo, commits in grouped:
+        lines.append(f"## `{repo}`  ({len(commits)})")
+        lines.append("")
+        lines.append(f"| Merge time | Patch | {person_col} | Subject |")
+        lines.append("|---|---|---|---|")
+        for c in commits:
+            person = _person(c, by_committer).replace("|", "\\|")
+            subj = c.subject.replace("|", "\\|").replace("\n", " ")
+            patch = f"[{_patch_label(c)}]({c.patch_url})" if c.patch_url else "-"
+            lines.append(
+                f"| {c.committer_date} | {patch} | {person} | {subj} |"
+            )
+        lines.append("")
+    return "\n".join(lines)

git_merge_list/query.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Junbo Zheng
+"""Query commits from a single repo via `git log`, filtered by committer date.
+
+`git log --since`/`--until` filter on the committer date (merge time), not the
+author date — exactly the semantics the tool promises. We use a NUL-separated
+`-z` output with a unit-separator field delimiter so commit bodies (which may
+contain newlines) parse reliably.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass
+
+FIELD = "\x1f"  # unit separator: between fields within one commit
+CHANGE_ID_RE = re.compile(r"^\s*Change-Id:\s*(I[0-9a-f]{40})\s*$", re.MULTILINE)
+
+
+@dataclass
+class Commit:
+    repo: str
+    hash: str
+    author_name: str
+    author_email: str
+    committer_name: str
+    committer_email: str
+    committer_date: str  # ISO 8601 from %cI
+    subject: str
+    change_id: str
+    patch_url: str
+
+
+def query_repo(
+    repo: str,
+    since: str | None,
+    until: str | None,
+    *,
+    author: str | None = None,
+    max_count: int | None = None,
+    reverse: bool = False,
+    base_url: str | None = None,
+) -> tuple[list[Commit], str]:
+    """Return `(commits, stderr)`. `stderr` is '' on success.
+
+    `base_url` is the pre-derived Gerrit base for this repo; passing it in
+    keeps the gerrit module out of the hot loop.
+    """
+    fmt = FIELD.join(["%H", "%an", "%ae", "%cn", "%ce", "%cI", "%s", "%B"])
+    args: list[str] = [
+        "git",
+        "-C",
+        repo,
+        "log",
+        "-z",
+        f"--format={fmt}",
+    ]
+    if since:
+        args.append(f"--since={since}")
+    if until:
+        args.append(f"--until={until}")
+    if author:
+        args.append(f"--author={author}")
+    if max_count:
+        args.append(f"--max-count={max_count}")
+    if reverse:
+        args.append("--reverse")
+
+    res = subprocess.run(args, capture_output=True, text=True, check=False)
+    if res.returncode != 0:
+        return [], (res.stderr or f"git log failed (exit {res.returncode})").strip()
+
+    commits: list[Commit] = []
+    for rec in res.stdout.split("\x00"):
+        if not rec:
+            continue
+        parts = rec.split(FIELD)
+        if len(parts) < 8:
+            continue
+        h, an, ae, cn, ce, ci, subj, body = parts[:8]
+        m = CHANGE_ID_RE.search(body or "")
+        cid = m.group(1) if m else ""
+        commits.append(
+            Commit(
+                repo=repo,
+                hash=h,
+                author_name=an,
+                author_email=ae,
+                committer_name=cn,
+                committer_email=ce,
+                committer_date=ci,
+                subject=subj,
+                change_id=cid,
+                patch_url=gerrit_patch_url(base_url, cid, h),
+            )
+        )
+    return commits, ""
+
+
+# Local import shim to avoid a circular import at module load time.
+def gerrit_patch_url(base: str | None, cid: str, h: str) -> str:
+    from .gerrit import patch_url
+
+    return patch_url(base, cid, h)

git_merge_list/timeparse.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Junbo Zheng
+"""Parse user-supplied time selectors into git `--since`/`--until` strings.
+
+All ranges are interpreted in the local timezone unless `--tz` overrides it.
+git's `--since`/`--until` filter on the committer date (merge time), which is
+exactly what we want — not the author date (commit time).
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from datetime import datetime, timedelta
+from zoneinfo import ZoneInfo
+
+DAY_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+HOUR_RE = re.compile(r"^(\d{4})-(\d{2})-(\d{2})[ T](\d{2})$")
+OFFSET_RE = re.compile(r"[+-]\d{2}:?\d{2}$")
+
+
+def local_offset_str() -> str:
+    """Return the system local offset as a git-style `+HHMM` string."""
+    is_dst = time.localtime().tm_isdst > 0
+    off = -time.altzone if is_dst else -time.timezone
+    sign = "+" if off >= 0 else "-"
+    off = abs(off)
+    return f"{sign}{off // 3600:02d}{(off % 3600) // 60:02d}"
+
+
+def parse_tz(tz_arg: str | None) -> str:
+    """Resolve a `--tz` argument (or None) to a `+HHMM` string.
+
+    Accepts `+HHMM` / `+HH:MM` / `Z`, or an IANA zone name like
+    `Asia/Shanghai`. Falls back to the system offset on any parse failure.
+    """
+    if not tz_arg:
+        return local_offset_str()
+    arg = tz_arg.strip()
+    if arg.upper() == "Z":
+        return "+0000"
+    if arg.startswith(("+", "-")):
+        clean = arg.replace(":", "")
+        if len(clean) == 5:
+            return clean
+        if len(clean) == 3:  # e.g. "+8" → "+0800"
+            return f"{clean[0]}0{clean[1:]}00"
+        return local_offset_str()
+    try:
+        off = ZoneInfo(arg).utcoffset(datetime.now())
+        total = int(off.total_seconds())
+        sign = "+" if total >= 0 else "-"
+        total = abs(total)
+        return f"{sign}{total // 3600:02d}{(total % 3600) // 60:02d}"
+    except Exception:
+        return local_offset_str()
+
+
+def _ensure_tz(s: str, tz: str) -> str:
+    """Append the offset to a bare time string unless it already carries one."""
+    s = s.strip()
+    if OFFSET_RE.search(s) or s.endswith("Z"):
+        return s
+    if DAY_RE.match(s):
+        return f"{s} 00:00 {tz}"
+    return f"{s} {tz}"
+
+
+def build_range(
+    *,
+    day: str | None,
+    hour: str | None,
+    since: str | None,
+    until: str | None,
+    tz_arg: str | None,
+) -> tuple[str | None, str | None]:
+    """Turn one of --day / --hour / --since(+--until) into `(since, until)`.
+
+    Raises ValueError on malformed input or on no time selector being given.
+    `until` is None when only `--since` is provided (means: since → now).
+    """
+    tz = parse_tz(tz_arg)
+    selectors = sum(bool(x) for x in (day, hour, since))
+    if selectors == 0:
+        raise ValueError("no time selector given; pass one of --day / --hour / --since")
+    if selectors > 1:
+        raise ValueError("--day / --hour / --since are mutually exclusive; pick one")
+
+    if day:
+        if not DAY_RE.match(day):
+            raise ValueError(f"--day expects YYYY-MM-DD, got: {day!r}")
+        start = datetime.strptime(day, "%Y-%m-%d")
+        end = start + timedelta(days=1)
+        return (
+            f"{start.strftime('%Y-%m-%d')} 00:00 {tz}",
+            f"{end.strftime('%Y-%m-%d')} 00:00 {tz}",
+        )
+
+    if hour:
+        m = HOUR_RE.match(hour)
+        if not m:
+            raise ValueError(f"--hour expects 'YYYY-MM-DD HH', got: {hour!r}")
+        y, mo, d, h = (int(x) for x in m.groups())
+        start = datetime(y, mo, d, h)
+        end = start + timedelta(hours=1)
+        return (
+            f"{start.strftime('%Y-%m-%d %H:%M')} {tz}",
+            f"{end.strftime('%Y-%m-%d %H:%M')} {tz}",
+        )
+
+    # --since (until optional)
+    since_str = _ensure_tz(since, tz)
+    until_str = _ensure_tz(until, tz) if until else None
+    return since_str, until_str

git_merge_list-0.0.1.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: git-merge-list
+Version: 0.0.1
+Summary: Recursively scan git repos under a path and list commits merged within a time range (by committer date), with Gerrit patch links.
+Project-URL: Homepage, https://github.com/Junbo-Zheng/git-merge-list
+Project-URL: Issues, https://github.com/Junbo-Zheng/git-merge-list/issues
+Author: Junbo Zheng
+License: Apache-2.0
+License-File: LICENSE
+Keywords: commits,gerrit,git,merge-log,repo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# git-merge-list
+
+![PyPI](https://img.shields.io/pypi/v/git-merge-list)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/git-merge-list)
+![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+
+Recursively scan git repositories under a path and list commits **merged**
+within a time range — by **committer date**, not author date — across every
+repo it finds, with Gerrit patch links.
+
+Built for the recurring question: _"a problem showed up; who landed what
+into these repos in this window, and what are the patch links?"_
+
+## Why committer date
+
+In a Gerrit workflow the **author date** is when the developer wrote the
+patch; the **committer date** is when it actually landed on the branch
+(merged / cherry-picked / rebased in). When you `git pull` / `repo sync`
+to latest and ask "what got merged on July 5th", you want committer date.
+`git log --since`/`--until` filter on committer date, so that is what this
+tool uses.
+
+## Features
+
+- **Three time selectors** (pick one): `--day`, `--hour`, or `--since`/`--until`.
+- **Cross-repo by default**: recursively finds every `.git` under the path —
+  standalone repos **and** `repo`-tool-managed multi-repos. Nested submodules
+  are picked up too.
+- **Gerrit patch links**: host derived from each repo's `origin` remote;
+  link is `https://<host>/q/<Change-Id>` (clickable, no network/auth needed).
+- **Two outputs**: a colored terminal table grouped by repo, plus a Markdown
+  report file.
+- **Zero runtime dependencies** — standard library only.
+
+## Install
+
+Prerequisite: `git` must be on `PATH` (the tool shells out to `git log` /
+`git config`). Python ≥ 3.10.
+
+From PyPI:
+
+```bash
+pip install git-merge-list
+git-merge-list --version
+```
+
+Editable install (for development, with test/lint deps):
+
+```bash
+pip install -e ".[dev]"
+```
+
+Or run from source with no install:
+
+```bash
+./main.py --version
+```
+
+## Usage
+
+```bash
+# Whole calendar day (local timezone)
+git-merge-list /path/to/workspace --day 2026-07-05
+
+# Whole calendar hour
+git-merge-list /path/to/workspace --hour "2026-07-05 14"
+
+# Precise range (--until defaults to now when omitted)
+git-merge-list /path/to/workspace --since "2026-07-05 14:00" --until "2026-07-05 15:30"
+
+# Force a timezone for the selectors
+git-merge-list . --day 2026-07-05 --tz Asia/Shanghai
+
+# Filter by submitter; show committer instead of author
+git-merge-list . --since "2026-07-05" --author "alice" --by-committer
+```
+
+> [!NOTE]
+> The tool only reads local state — it does not pull. Run `git pull` /
+> `repo sync` to latest first.
+
+### Example
+
+Terminal output (colors shown when stdout is a TTY and `NO_COLOR` is unset):
+
+```text
+$ git-merge-list /path/to/workspace --day 2026-07-05
+git-merge-list  range: 2026-07-05 .. 2026-07-06
+3 commit(s) across 2 repo(s)
+
+platform/native  (2)
+  Merge time                Patch                                        Submitter           Subject
+  2026-07-05 09:12:33 +0800 https://gerrit.example.com/q/I1a2b3c4d5e6   Alice <a@x.example>  Fix audio underrun on cold start
+  2026-07-05 14:45:10 +0800 https://gerrit.example.com/q/I2b3c4d5e6f7   Bob <b@x.example>    Refactor PCM open path
+
+vendor/hal  (1)
+  Merge time                Patch                                        Submitter           Subject
+  2026-07-05 10:03:55 +0800 https://gerrit.example.com/q/I3c4d5e6f7g8   Carol <c@x.example>  Lower default buffer size
+```
+
+A Markdown report with the same content is written next to the run
+(`git-merge-list-report-<timestamp>.md` by default).
+
+### Output
+
+- **Terminal**: a color table grouped by repo, columns
+  `Merge time | Patch | Submitter | Subject`. Color is gated on TTY and
+  `NO_COLOR`.
+- **Markdown report**: written to `git-merge-list-report-<timestamp>.md`
+  (override with `-o`, suppress with `--no-markdown`).
+
+> [!TIP]
+> To preview the rendered Markdown report: `grip <file.md>` (local server) or
+> `pandoc <file.md> -s -o <file.html>` (standalone HTML).
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `path` | root path to scan (default: current directory) |
+| `--day YYYY-MM-DD` | whole calendar day |
+| `--hour "YYYY-MM-DD HH"` | whole calendar hour |
+| `--since ...` | start time (inclusive); `--until` defaults to now |
+| `--until ...` | end time |
+| `--tz ...` | `+0800` \| `+08:00` \| `Z` \| `Asia/Shanghai` (default: system local) |
+| `--author REGEX` | match author name/email |
+| `--by-committer` | show committer (not author) as the submitter column |
+| `--max-count N` | per-repo commit cap |
+| `--reverse` | oldest-first within each repo |
+| `-o, --output PATH` | Markdown report path |
+| `--no-markdown` | do not write a Markdown report file |
+| `-V, --version` | show version and exit |
+
+## How it works
+
+- **Repo discovery**: a "repo" is any directory containing a `.git` entry —
+  a `.git` directory (normal checkout) or a `.git` file (worktree /
+  submodule). The scan never enters `.git/` or `.repo/` metadata, but keeps
+  walking a found repo's subdirectories so nested submodules are found.
+  Each `repo`-tool project is itself a normal git repo, so it is covered.
+- **Time field**: `git log --since`/`--until` filter on the committer date.
+  Author date is not used for filtering.
+- **Patch link**: the Gerrit host is parsed from each repo's `origin`
+  remote URL. For `ssh://` remotes the port (e.g. Gerrit's 29418) is
+  dropped — that's the push port; the web UI runs on HTTPS (443). The link
+  `https://<host>/q/<Change-Id>` is Gerrit's search-redirect URL. Commits
+  without a `Change-Id` fall back to the commit hash.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                   # tests
+black --check src tests  # format check (CI-enforced)
+python -m build          # build wheel
+```
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).
+

git_merge_list-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+git_merge_list/__init__.py,sha256=fX5gJgIBUSJzqvtwA4wHQjUeWpQWEBZ4wQscH4WdLew,170
+git_merge_list/cli.py,sha256=3eejB8FdYrr5Sy0V0pOX8l6IVG7vVBL6hA_zMm3KJ2s,4699
+git_merge_list/discover.py,sha256=O9rbmCJrXvZcI1TeDtJTq1Xwh5OXSdFJAU3Jwz8t-wA,1410
+git_merge_list/gerrit.py,sha256=7LW5TPnkVXzVQq1rnS80qw8X145DIYwpKXoupLZvDp8,2731
+git_merge_list/output.py,sha256=1S2RDvIKsFCbMTFaZF_v_Del_FGUU_pO1iA762qoLxg,4020
+git_merge_list/query.py,sha256=UNXhZS7LfrOzaiQyplYFYlZWQCahhSdr8JVCfAOcR8c,3001
+git_merge_list/timeparse.py,sha256=be_a6tk-SKAwwi99syhVwm_vtHbTdoWONmmPUeNpLDA,3823
+git_merge_list-0.0.1.dist-info/METADATA,sha256=lOi_J6ffCUXfqQF4p7UwBJOKbgLLuWM_3-G1TKkFLXc,7116
+git_merge_list-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+git_merge_list-0.0.1.dist-info/entry_points.txt,sha256=YUnxfDK7Y8UuXgMlErZoc_gVyhqOwWnzpveD2r0k8H0,59
+git_merge_list-0.0.1.dist-info/licenses/LICENSE,sha256=NfPSZxmx_2JKSCbHTgRt9Ajzpt3qAe7Wp-NEYNq8BY8,11341
+git_merge_list-0.0.1.dist-info/RECORD,,

git_merge_list-0.0.1.dist-info/WHEEL

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

git_merge_list-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-merge-list = git_merge_list.cli:main

git_merge_list-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Junbo Zheng
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.