git-gerrit 3.0.0__tar.gz → 3.3.0__tar.gz

{git_gerrit-3.0.0/git_gerrit.egg-info → git_gerrit-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git_gerrit
-Version: 3.0.0
+Version: 3.3.0
 Summary: Gerrit review system command line tools.
 Home-page: https://github.com/meffie/git-gerrit
 Author: Michael Meffie
@@ -12,6 +12,7 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development
+Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 Requires-Dist: sh
 Requires-Dist: pygerrit2
@@ -19,6 +20,7 @@ Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
+Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: license
 Dynamic: license-file
@@ -39,7 +41,7 @@ with the **pygerrit2** package to access the Gerrit REST API.
 Commands
 ========
 
-.. code-block:: console
+**git-gerrit** commands::
 
     git gerrit-checkout          Fetch then checkout by gerrit number.
     git gerrit-cherry-pick       Cherry pick from upstream branch by gerrit number to make a new gerrit.
@@ -57,16 +59,32 @@ Installation
 ============
 
 .. _pipx: https://pipx.pypa.io/stable/
+.. _uv: https://github.com/astral-sh/uv
+
+The recommended way to install **git-gerrit** is with `uv`_ or `pipx`_.
+
+To install with ``uv``, run the following as a regular user:
 
-Install with `pipx`_::
+.. code-block:: console
+
+    uv tool install git-gerrit
+    uv tool update-shell
 
-    $ pipx install git-gerrit
+The ``uv tool update-shell`` command adds the installed commands to your
+shell's PATH.  Restart your shell after running ``update-shell``.
 
-Be sure your ``PATH`` has been updated to run **pipx** installed commands::
+To install with ``pipx_``, run the following as a regular user:
 
-    $ pipx ensurepath
+.. code-block:: console
 
-If **pipx** is not available, then install in a project local virtualenv::
+    pipx install git-gerrit
+    pipx ensurepath
+
+The ``pipx ensurepath`` command adds the installed commands to your shell's
+PATH.  Restart you shell after running ``ensurepath``.
+
+Alternatively, you can install **git-gerrit** directly into a local virtual
+environment with ``pip``::
 
     $ cd <my-project-directory>
     $ python3 -m venv .venv
@@ -74,7 +92,6 @@ If **pipx** is not available, then install in a project local virtualenv::
     (.venv) $ pip install -U pip setuptools
     (.venv) $ pip install git-gerrit
 
-
 Setup
 =====
 
@@ -101,6 +118,16 @@ Setup a local OpenAFS git repo::
     $ git config --local gerrit.project openafs
     $ git gerrit-install-hooks
 
+Fetch all of the change commits from the upstream gerrit system to your local
+repository and create the local sqlite database. This is a heavy weight operation
+and is only needed for **git gerrit-log** and **git gerrit-number**::
+
+    $ git gerrit-sync
+    ✔ Fetching changes from https://gerrit.example.com/example
+    ✔ Updating local database
+    ✔ Scanning commit messages
+    Done.
+
 Find open gerrits on the master branch::
 
     $ git gerrit-query is:open branch:master
@@ -163,14 +190,14 @@ Cherry-pick a gerrit onto the current branch::
 
 Show gerrit numbers in the checked out branch in the local git repo::
 
-    $ git gerrit-log
+    $ git gerrit-log -n3
     12958 f47cb2d Suppress statement not reached warnings under Solaris Studio
     12957 306f0f3 afs: squash empty declaration warning
     12955 e006609 libafs: git ignore build artifacts on Solaris
 
 Show gerrit numbers by a revision in the local git repo::
 
-    $ git gerrit-log openafs-stable-1_8_0
+    $ git gerrit-log -n3 openafs-stable-1_8_0
     12953 a08327f Update NEWS for 1.8.0 final release
     12938 acb0e84 afs_pioctl: avoid -Wpointer-sign
     12950 b73863b LINUX: fix RedHat 7.5 ENOTDIR issues
@@ -184,7 +211,7 @@ Show gerrit numbers by a range of revisions in the local git repo::
 
 Show just the gerrit numbers and subjects in the local git repo::
 
-    $ git gerrit-log --format='{number}: {subject}'
+    $ git gerrit-log -n3 --format='{number}: {subject}'
     12958: Suppress statement not reached warnings under Solaris Studio
     12957: afs: squash empty declaration warning
     12955: libafs: git ignore build artifacts on Solaris

{git_gerrit-3.0.0 → git_gerrit-3.3.0}/README.rst

@@ -12,7 +12,7 @@ with the **pygerrit2** package to access the Gerrit REST API.
 Commands
 ========
 
-.. code-block:: console
+**git-gerrit** commands::
 
     git gerrit-checkout          Fetch then checkout by gerrit number.
     git gerrit-cherry-pick       Cherry pick from upstream branch by gerrit number to make a new gerrit.
@@ -30,16 +30,32 @@ Installation
 ============
 
 .. _pipx: https://pipx.pypa.io/stable/
+.. _uv: https://github.com/astral-sh/uv
+
+The recommended way to install **git-gerrit** is with `uv`_ or `pipx`_.
+
+To install with ``uv``, run the following as a regular user:
 
-Install with `pipx`_::
+.. code-block:: console
+
+    uv tool install git-gerrit
+    uv tool update-shell
 
-    $ pipx install git-gerrit
+The ``uv tool update-shell`` command adds the installed commands to your
+shell's PATH.  Restart your shell after running ``update-shell``.
 
-Be sure your ``PATH`` has been updated to run **pipx** installed commands::
+To install with ``pipx_``, run the following as a regular user:
 
-    $ pipx ensurepath
+.. code-block:: console
 
-If **pipx** is not available, then install in a project local virtualenv::
+    pipx install git-gerrit
+    pipx ensurepath
+
+The ``pipx ensurepath`` command adds the installed commands to your shell's
+PATH.  Restart you shell after running ``ensurepath``.
+
+Alternatively, you can install **git-gerrit** directly into a local virtual
+environment with ``pip``::
 
     $ cd <my-project-directory>
     $ python3 -m venv .venv
@@ -47,7 +63,6 @@ If **pipx** is not available, then install in a project local virtualenv::
     (.venv) $ pip install -U pip setuptools
     (.venv) $ pip install git-gerrit
 
-
 Setup
 =====
 
@@ -74,6 +89,16 @@ Setup a local OpenAFS git repo::
     $ git config --local gerrit.project openafs
     $ git gerrit-install-hooks
 
+Fetch all of the change commits from the upstream gerrit system to your local
+repository and create the local sqlite database. This is a heavy weight operation
+and is only needed for **git gerrit-log** and **git gerrit-number**::
+
+    $ git gerrit-sync
+    ✔ Fetching changes from https://gerrit.example.com/example
+    ✔ Updating local database
+    ✔ Scanning commit messages
+    Done.
+
 Find open gerrits on the master branch::
 
     $ git gerrit-query is:open branch:master
@@ -136,14 +161,14 @@ Cherry-pick a gerrit onto the current branch::
 
 Show gerrit numbers in the checked out branch in the local git repo::
 
-    $ git gerrit-log
+    $ git gerrit-log -n3
     12958 f47cb2d Suppress statement not reached warnings under Solaris Studio
     12957 306f0f3 afs: squash empty declaration warning
     12955 e006609 libafs: git ignore build artifacts on Solaris
 
 Show gerrit numbers by a revision in the local git repo::
 
-    $ git gerrit-log openafs-stable-1_8_0
+    $ git gerrit-log -n3 openafs-stable-1_8_0
     12953 a08327f Update NEWS for 1.8.0 final release
     12938 acb0e84 afs_pioctl: avoid -Wpointer-sign
     12950 b73863b LINUX: fix RedHat 7.5 ENOTDIR issues
@@ -157,7 +182,7 @@ Show gerrit numbers by a range of revisions in the local git repo::
 
 Show just the gerrit numbers and subjects in the local git repo::
 
-    $ git gerrit-log --format='{number}: {subject}'
+    $ git gerrit-log -n3 --format='{number}: {subject}'
     12958: Suppress statement not reached warnings under Solaris Studio
     12957: afs: squash empty declaration warning
     12955: libafs: git ignore build artifacts on Solaris

git_gerrit-3.3.0/git_gerrit/__version__.py

@@ -0,0 +1 @@
+VERSION = "3.3.0"

{git_gerrit-3.0.0 → git_gerrit-3.3.0}/git_gerrit/cli.py

@@ -460,7 +460,10 @@ def main_git_gerrit_number(argv=None):
             for p in change['cherry_picked_to']:
                 print(p or "")
         elif args.checkout:
-            print(git.git.checkout(change['commit_id'], detach=True))
+            number = change['number']
+            patchset = change['current_patchset']
+            print(f"checking out {number},{patchset}")
+            git.checkout(change['commit_id'])
         elif args.show:
             print(git.git.show(change['commit_id']))
         else:

{git_gerrit-3.0.0 → git_gerrit-3.3.0}/git_gerrit/core.py

@@ -492,25 +492,38 @@ def sync(limit=None):
                 parts = refname.split("/")
                 number = int(parts[3])
                 patchset = int(parts[4])
-                db.add_change(number, patchset, commit_id)
+                db.add_patchset(number, patchset, commit_id)
                 spinner.spin()
 
     # It is not practical to read every commit message, and normally, we only
     # care about the current patchsets, so scan just the current patchsets
     # (that is the max patchset number of each change number). Also, limit the
-    # number of changes to be scanned, since we normally care about jus the
-    # most recent numbers. This amoritizes the scanning, so the first
+    # number of changes to be scanned, since we normally care about just the
+    # most recent numbers. This amortizes the scanning, so the first
     # git-gerrit-sync will scan a reasonable number of changes, and later syncs
     # will process older changes.
+    no_change_id = 0
     with Spinner("Scanning commit messages") as spinner:
         with GitGerritDB() as db:
             for c in db.get_current_patchsets(limit=limit):
                 if c['flags'] != 1:
+                    number = c['number']
+                    current_patchset = c['current_patchset']
                     commit_id = c['commit_id']
                     change_id = git.change_id(commit_id)
+                    if change_id is None:
+                        # Some early changes were merged before gerrit enforced
+                        # a Change-Id trailer. Record the commit, but skip the
+                        # gerrit_changes row, which is keyed by Change-Id.
+                        no_change_id += 1
+                    else:
+                        db.record_change(number, current_patchset, change_id)
+
                     picked_from = git.cherry_picked_from(commit_id)
                     db.update_commit(commit_id, change_id, picked_from, 1)
                     spinner.spin()
 
+    if no_change_id:
+        print(f"Skipped {no_change_id} change(s) with no Change-Id.")
     print("Done.")
     return 0

{git_gerrit-3.0.0 → git_gerrit-3.3.0}/git_gerrit/db.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2025 Sine Nomine Associates
+# Copyright (c) 2025-2026 Sine Nomine Associates
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -25,7 +25,7 @@ from git_gerrit.git import Git
 
 DATABASE = "git-gerrit.db"
 MAGIC = 0x67697467  # "gitg"
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 MIGRATION_SCRIPTS = [
     """
     CREATE TABLE changes (
@@ -42,6 +42,39 @@ MIGRATION_SCRIPTS = [
         FOREIGN KEY (commit_id) REFERENCES commits(change_commit_id)
     );
     """,
+    """
+    ALTER TABLE changes RENAME TO gerrit_patchsets;
+    ALTER TABLE gerrit_patchsets RENAME COLUMN change_number TO number;
+    ALTER TABLE gerrit_patchsets RENAME COLUMN change_patchset TO patchset;
+    ALTER TABLE gerrit_patchsets RENAME COLUMN change_commit_id TO commit_id;
+
+    ALTER TABLE commits RENAME COLUMN commit_change_id TO change_id;
+    ALTER TABLE commits RENAME COLUMN commit_picked_from TO cherry_picked_from;
+    ALTER TABLE commits RENAME COLUMN commit_flags TO flags;
+
+    /* One canonical row per Change-Id. When several gerrit changes share a
+       Change-Id (a cherry-pick that reused it instead of generating a new
+       one), the lowest number is canonical and the rest are recorded in
+       gerrit_duplicate_changes. */
+    CREATE TABLE gerrit_changes (
+        number INTEGER PRIMARY KEY,
+        current_patchset INTEGER,
+        change_id TEXT NOT NULL UNIQUE,
+        merged_as TEXT  /* NULL if not merged */
+    );
+    CREATE TABLE gerrit_duplicate_changes (
+        number INTEGER PRIMARY KEY,        /* A non-canonical change number. */
+        change_id TEXT NOT NULL,           /* Its Change-Id. */
+        canonical_number INTEGER NOT NULL, /* The canonical change number. */
+        FOREIGN KEY (canonical_number) REFERENCES gerrit_changes(number)
+    );
+    CREATE INDEX gerrit_duplicate_changes_change_id
+        ON gerrit_duplicate_changes (change_id);
+
+    /* Rescan every commit message so the canonical/duplicate split is built
+       from the whole history, not just changes seen since the upgrade. */
+    UPDATE commits SET flags = 0;
+    """,
 ]
 
 
@@ -163,9 +196,9 @@ class GitGerritDB:
             data = None
         return data
 
-    def add_change(self, number, patchset, commit_id):
+    def add_patchset(self, number, patchset, commit_id):
         """
-        Adds a new change to the database.
+        Adds a new patchset to the database.
 
         Args:
             number (int): The change number.
@@ -176,21 +209,128 @@ class GitGerritDB:
             cursor.execute(
                 """
                 INSERT OR IGNORE INTO commits
-                (commit_id, commit_flags)
+                (commit_id, flags)
                 VALUES (?, 0)
                 """,
                 (commit_id,),
             )
             cursor.execute(
                 """
-                INSERT OR IGNORE INTO changes
-                (change_number, change_patchset, change_commit_id)
+                INSERT OR IGNORE INTO gerrit_patchsets
+                (number, patchset, commit_id)
                 VALUES (?, ?, ?)
                 """,
                 (number, patchset, commit_id),
             )
             self._dirty = True
 
+    def record_change(self, number, current_patchset, change_id):
+        """
+        Records a change, keeping gerrit_changes to one row per Change-Id.
+
+        The canonical change for a Change-Id is the one with the lowest
+        number. Any other change numbers that carry the same Change-Id are
+        moved to gerrit_duplicate_changes.
+
+        Args:
+            number (int): The gerrit change number.
+            current_patchset (int): The most recent patchset number.
+            change_id (str): The gerrit Change-Id.
+
+        Returns:
+            bool: True if `number` is the canonical change, False if it was
+                recorded as a duplicate.
+        """
+        with Cursor(self) as cursor:
+            cursor.execute(
+                "SELECT number FROM gerrit_changes WHERE change_id = ?",
+                (change_id,),
+            )
+            row = cursor.fetchone()
+            canonical = row["number"] if row else None
+
+            if canonical == number:
+                # Rescan of the canonical change; just refresh the patchset.
+                cursor.execute(
+                    "UPDATE gerrit_changes SET current_patchset = ? "
+                    "WHERE number = ?",
+                    (current_patchset, number),
+                )
+                self._dirty = True
+                return True
+
+            # Forget any stale record of this number before re-recording it.
+            cursor.execute("DELETE FROM gerrit_changes WHERE number = ?", (number,))
+            cursor.execute(
+                "DELETE FROM gerrit_duplicate_changes WHERE number = ?", (number,)
+            )
+            self._dirty = True
+
+            if canonical is not None and number > canonical:
+                # A lower-numbered change is canonical; sidebar this one.
+                cursor.execute(
+                    "INSERT INTO gerrit_duplicate_changes "
+                    "(number, change_id, canonical_number) VALUES (?, ?, ?)",
+                    (number, change_id, canonical),
+                )
+                return False
+
+            # `number` becomes canonical: the Change-Id is new, or `number` is
+            # lower than the current canonical and takes it over. Demote the
+            # old canonical and re-point its duplicates.
+            demoted = []
+            if canonical is not None:
+                cursor.execute(
+                    "SELECT number FROM gerrit_duplicate_changes "
+                    "WHERE change_id = ?",
+                    (change_id,),
+                )
+                demoted = [r["number"] for r in cursor.fetchall()]
+                demoted.append(canonical)
+                cursor.execute(
+                    "DELETE FROM gerrit_duplicate_changes WHERE change_id = ?",
+                    (change_id,),
+                )
+                cursor.execute(
+                    "DELETE FROM gerrit_changes WHERE number = ?", (canonical,)
+                )
+            cursor.execute(
+                "INSERT INTO gerrit_changes "
+                "(number, current_patchset, change_id) VALUES (?, ?, ?)",
+                (number, current_patchset, change_id),
+            )
+            for dup in demoted:
+                cursor.execute(
+                    "INSERT INTO gerrit_duplicate_changes "
+                    "(number, change_id, canonical_number) VALUES (?, ?, ?)",
+                    (dup, change_id, number),
+                )
+            return True
+
+    def get_change(self, change_id):
+        """
+        Returns the canonical change for a Change-Id, or None.
+
+        Args:
+            change_id (str): The gerrit Change-Id.
+
+        Returns:
+            dict: The gerrit_changes row, or None if the Change-Id is unknown.
+        """
+        with Cursor(self) as cursor:
+            cursor.execute(
+                "SELECT number, current_patchset, change_id, merged_as "
+                "FROM gerrit_changes WHERE change_id = ?",
+                (change_id,),
+            )
+            return self._as_dict(cursor.fetchone())
+
+    def count_duplicate_changes(self):
+        """Returns the number of rows in gerrit_duplicate_changes."""
+        with Cursor(self) as cursor:
+            cursor.execute("SELECT COUNT(*) FROM gerrit_duplicate_changes")
+            return cursor.fetchone()[0]
+
     def update_commit(self, commit_id, change_id, picked_from, flags):
         """
         Updates the details of a commit.
@@ -205,7 +345,7 @@ class GitGerritDB:
             cursor.execute(
                 """
                 UPDATE commits
-                SET commit_change_id = ?, commit_picked_from = ?, commit_flags = ?
+                SET change_id = ?, cherry_picked_from = ?, flags = ?
                 WHERE commit_id == ?
                 """,
                 (change_id, picked_from, flags, commit_id),
@@ -214,13 +354,16 @@ class GitGerritDB:
 
     def get_current_patchsets(self, limit=None):
         """
-        Retrieves the current patchsets for all changes.
+        Retrieves the current patchset of every change.
+
+        Yields one row per change number: its highest-numbered patchset
+        joined with the commit details, ordered by change number descending.
 
         Args:
-            limit (int, optional): The maximum number of patchsets to retrieve.
+            limit (int, optional): The maximum number of changes to retrieve.
 
         Yields:
-            dict: A dictionary representing a patchset.
+            dict: A dictionary representing the current patchset of a change.
         """
         if self._dirty:
             self._conn.commit()
@@ -235,16 +378,16 @@ class GitGerritDB:
             cursor.execute(
                 f"""
                 SELECT
-                    ch.change_number AS number,
-                    MAX(ch.change_patchset) AS current_patchset,
-                    ch.change_commit_id AS commit_id,
-                    co.commit_change_id AS change_id,
-                    co.commit_picked_from AS cherry_picked_from,
-                    co.commit_flags AS flags
-                FROM changes AS ch
-                LEFT JOIN commits AS co ON co.commit_id = ch.change_commit_id
-                GROUP BY ch.change_number
-                ORDER BY ch.change_number DESC
+                    ps.number AS number,
+                    MAX(ps.patchset) AS current_patchset,
+                    ps.commit_id AS commit_id,
+                    co.change_id AS change_id,
+                    co.cherry_picked_from AS cherry_picked_from,
+                    co.flags AS flags
+                FROM gerrit_patchsets AS ps
+                LEFT JOIN commits AS co ON co.commit_id = ps.commit_id
+                GROUP BY ps.number
+                ORDER BY ps.number DESC
                 {limit_clause}
                 """
             )
@@ -269,17 +412,17 @@ class GitGerritDB:
             cursor.execute(
                 """
                 SELECT
-                    ch.change_number AS number,
-                    MAX(ch.change_patchset) AS current_patchset,
-                    ch.change_commit_id AS commit_id,
-                    co.commit_change_id AS change_id,
-                    co.commit_picked_from AS cherry_picked_from,
-                    co.commit_flags AS flags
-                FROM changes AS ch
-                LEFT JOIN commits AS co ON co.commit_id = ch.change_commit_id
-                WHERE ch.change_number = ?
-                GROUP BY ch.change_number
-                ORDER BY ch.change_number DESC
+                    ps.number AS number,
+                    MAX(ps.patchset) AS current_patchset,
+                    ps.commit_id AS commit_id,
+                    co.change_id AS change_id,
+                    co.cherry_picked_from AS cherry_picked_from,
+                    co.flags AS flags
+                FROM gerrit_patchsets AS ps
+                LEFT JOIN commits AS co ON co.commit_id = ps.commit_id
+                WHERE ps.number = ?
+                GROUP BY ps.number
+                ORDER BY ps.number DESC
                 LIMIT 1
                 """,
                 (number,),
@@ -307,15 +450,15 @@ class GitGerritDB:
             cursor.execute(
                 """
                 SELECT
-                    ch.change_number AS number,
-                    ch.change_patchset AS patchset,
-                    ch.change_commit_id AS commit_id,
-                    co.commit_change_id AS change_id,
-                    co.commit_picked_from AS cherry_picked_from,
-                    co.commit_flags AS flags
-                FROM changes AS ch
-                LEFT JOIN commits AS co ON co.commit_id = ch.change_commit_id
-                WHERE ch.change_commit_id = ?
+                    ps.number AS number,
+                    ps.patchset AS patchset,
+                    ps.commit_id AS commit_id,
+                    co.change_id AS change_id,
+                    co.cherry_picked_from AS cherry_picked_from,
+                    co.flags AS flags
+                FROM gerrit_patchsets AS ps
+                LEFT JOIN commits AS co ON co.commit_id = ps.commit_id
+                WHERE ps.commit_id = ?
                 LIMIT 1
                 """,
                 (commit_id,),
@@ -345,11 +488,11 @@ class GitGerritDB:
                 """
                 SELECT
                     commit_id,
-                    commit_change_id,
-                    commit_picked_from,
-                    commit_flags
+                    change_id,
+                    cherry_picked_from,
+                    flags
                 FROM commits
-                WHERE commit_picked_from = ?
+                WHERE cherry_picked_from = ?
                 """,
                 (commit_picked_from,),
             )

{git_gerrit-3.0.0 → git_gerrit-3.3.0}/git_gerrit/git.py

@@ -22,6 +22,7 @@
 import os
 import re
 import sh
+import sys
 
 import urllib.request
 
@@ -186,7 +187,17 @@ class Git:
 
     def checkout(self, refname):
         """Run git checkout to checkout a change."""
-        self.git.checkout(refname)
+        try:
+            self.git(
+                "-c",
+                "advice.detachedHead=false",
+                "checkout",
+                refname,
+                _out=sys.stdout,
+                _err=sys.stderr,
+            )
+        except sh.ErrorReturnCode as e:
+            raise GitGerritError(f"Command failed: git checkout: {e.exit_code}")
 
     def log(self, refname=None, **options):
         """Run git log to show changes."""
@@ -249,10 +260,13 @@ class Git:
             return False
 
     def change_id(self, sha1):
+        # Scan the raw commit message rather than git's %(trailers) parser.
+        # The trailer parser rejects the whole footer block when it contains
+        # non-trailer lines (e.g. the "FIXES 135591" convention used by
+        # OpenAFS), which would hide an otherwise valid Change-Id.
         change_id = None
-        format_ = "%(trailers:key=Change-Id)"
-        for line in self.log(sha1, max_count=1, pretty=format_):
-            m = re.match(r'Change-Id: (I[0-9a-fA-F]+)', line)
+        for line in self.log(sha1, max_count=1, pretty="%B"):
+            m = re.match(r'^Change-Id: (I[0-9a-fA-F]+)', line)
             if m:
                 change_id = m.group(1)
         return change_id

{git_gerrit-3.0.0 → git_gerrit-3.3.0/git_gerrit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git_gerrit
-Version: 3.0.0
+Version: 3.3.0
 Summary: Gerrit review system command line tools.
 Home-page: https://github.com/meffie/git-gerrit
 Author: Michael Meffie
@@ -12,6 +12,7 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development
+Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 Requires-Dist: sh
 Requires-Dist: pygerrit2
@@ -19,6 +20,7 @@ Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
+Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: license
 Dynamic: license-file
@@ -39,7 +41,7 @@ with the **pygerrit2** package to access the Gerrit REST API.
 Commands
 ========
 
-.. code-block:: console
+**git-gerrit** commands::
 
     git gerrit-checkout          Fetch then checkout by gerrit number.
     git gerrit-cherry-pick       Cherry pick from upstream branch by gerrit number to make a new gerrit.
@@ -57,16 +59,32 @@ Installation
 ============
 
 .. _pipx: https://pipx.pypa.io/stable/
+.. _uv: https://github.com/astral-sh/uv
+
+The recommended way to install **git-gerrit** is with `uv`_ or `pipx`_.
+
+To install with ``uv``, run the following as a regular user:
 
-Install with `pipx`_::
+.. code-block:: console
+
+    uv tool install git-gerrit
+    uv tool update-shell
 
-    $ pipx install git-gerrit
+The ``uv tool update-shell`` command adds the installed commands to your
+shell's PATH.  Restart your shell after running ``update-shell``.
 
-Be sure your ``PATH`` has been updated to run **pipx** installed commands::
+To install with ``pipx_``, run the following as a regular user:
 
-    $ pipx ensurepath
+.. code-block:: console
 
-If **pipx** is not available, then install in a project local virtualenv::
+    pipx install git-gerrit
+    pipx ensurepath
+
+The ``pipx ensurepath`` command adds the installed commands to your shell's
+PATH.  Restart you shell after running ``ensurepath``.
+
+Alternatively, you can install **git-gerrit** directly into a local virtual
+environment with ``pip``::
 
     $ cd <my-project-directory>
     $ python3 -m venv .venv
@@ -74,7 +92,6 @@ If **pipx** is not available, then install in a project local virtualenv::
     (.venv) $ pip install -U pip setuptools
     (.venv) $ pip install git-gerrit
 
-
 Setup
 =====
 
@@ -101,6 +118,16 @@ Setup a local OpenAFS git repo::
     $ git config --local gerrit.project openafs
     $ git gerrit-install-hooks
 
+Fetch all of the change commits from the upstream gerrit system to your local
+repository and create the local sqlite database. This is a heavy weight operation
+and is only needed for **git gerrit-log** and **git gerrit-number**::
+
+    $ git gerrit-sync
+    ✔ Fetching changes from https://gerrit.example.com/example
+    ✔ Updating local database
+    ✔ Scanning commit messages
+    Done.
+
 Find open gerrits on the master branch::
 
     $ git gerrit-query is:open branch:master
@@ -163,14 +190,14 @@ Cherry-pick a gerrit onto the current branch::
 
 Show gerrit numbers in the checked out branch in the local git repo::
 
-    $ git gerrit-log
+    $ git gerrit-log -n3
     12958 f47cb2d Suppress statement not reached warnings under Solaris Studio
     12957 306f0f3 afs: squash empty declaration warning
     12955 e006609 libafs: git ignore build artifacts on Solaris
 
 Show gerrit numbers by a revision in the local git repo::
 
-    $ git gerrit-log openafs-stable-1_8_0
+    $ git gerrit-log -n3 openafs-stable-1_8_0
     12953 a08327f Update NEWS for 1.8.0 final release
     12938 acb0e84 afs_pioctl: avoid -Wpointer-sign
     12950 b73863b LINUX: fix RedHat 7.5 ENOTDIR issues
@@ -184,7 +211,7 @@ Show gerrit numbers by a range of revisions in the local git repo::
 
 Show just the gerrit numbers and subjects in the local git repo::
 
-    $ git gerrit-log --format='{number}: {subject}'
+    $ git gerrit-log -n3 --format='{number}: {subject}'
     12958: Suppress statement not reached warnings under Solaris Studio
     12957: afs: squash empty declaration warning
     12955: libafs: git ignore build artifacts on Solaris

{git_gerrit-3.0.0 → git_gerrit-3.3.0}/setup.py

@@ -19,6 +19,7 @@ setup(
     version=get_version(),
     description='Gerrit review system command line tools.',
     long_description=open('README.rst').read(),
+    long_description_content_type='text/x-rst',
     author='Michael Meffie',
     author_email='mmeffie@sinenomine.net',
     license='BSD-2-Clause',

{git_gerrit-3.0.0 → git_gerrit-3.3.0}/tests/test_core.py

@@ -11,6 +11,7 @@ from git_gerrit.core import (
     sync,
     update,
 )
+from git_gerrit.db import GitGerritDB, Cursor
 from git_gerrit.error import GitGerritError, GitGerritNotFoundError
 
 
@@ -105,10 +106,40 @@ def test_get_current_change__not_found(mock_modules):
 
 def test_sync(capsys, mock_modules):
     sync()
-    output = capsys.readouterr().out.splitlines()
-    print(output)
+    output = capsys.readouterr().out
     assert os.path.exists("mock-fetch")
     with open("mock-fetch", "r") as f:
         mock_fetch = f.read().splitlines()
     assert mock_fetch[0] == "https://gerrit.example.org/mayhem"
     assert mock_fetch[1] == "refs/changes/*:refs/changes/*"
+
+    # The mocked show-ref reports three changes:
+    #   change 1 - current patchset (ps 3) has Change-Id Ibc6dab9f...
+    #   change 2 - current patchset has no Change-Id trailer
+    #   change 3 - current patchset reuses change 1's Change-Id
+    with GitGerritDB() as db:
+        with Cursor(db) as cursor:
+            cursor.execute(
+                "SELECT number, current_patchset, change_id FROM gerrit_changes "
+                "ORDER BY number"
+            )
+            changes = [tuple(row) for row in cursor.fetchall()]
+        with Cursor(db) as cursor:
+            cursor.execute(
+                "SELECT number, canonical_number FROM gerrit_duplicate_changes"
+            )
+            duplicates = [tuple(row) for row in cursor.fetchall()]
+        with Cursor(db) as cursor:
+            cursor.execute(
+                "SELECT flags FROM commits WHERE commit_id = ?", (f"{4:040}",)
+            )
+            skipped_commit = cursor.fetchone()
+
+    cid = "Ibc6dab9f4a99d693ea03891ed7222fed9a07a85a"
+    # Change 1 is canonical (lowest number); change 3 is sidebarred as a
+    # duplicate; change 2 is skipped for want of a Change-Id.
+    assert changes == [(1, 3, cid)]
+    assert duplicates == [(3, 1)]
+    assert "Skipped 1 change(s) with no Change-Id." in output
+    # The skipped change's commit is still recorded and marked scanned.
+    assert skipped_commit["flags"] == 1

git_gerrit-3.3.0/tests/test_db.py

@@ -0,0 +1,205 @@
+import pytest
+
+from git_gerrit.db import GitGerritDB, Cursor, SCHEMA_VERSION
+
+
+@pytest.fixture
+def db(mock_modules):
+    with GitGerritDB() as db:
+        yield db
+
+
+@pytest.fixture
+def staged_db(mock_modules):
+    with GitGerritDB() as db:
+        db.add_patchset(101, 1, "aaa")
+        db.add_patchset(101, 2, "bbb")
+        db.add_patchset(102, 1, "ccc")
+        db.add_patchset(103, 1, "ddd")
+        db.add_patchset(103, 2, "eee")
+        db.add_patchset(103, 3, "fff")
+        db.update_commit("bbb", "I101", None, 0)
+        db.update_commit("ccc", "I102", None, 1)
+        db.update_commit("fff", "I103", "ggg", 0)
+        yield db
+
+
+def test_db_get_schema_version__returns_current_schema_version(db):
+    assert db._get_schema_version() == SCHEMA_VERSION
+
+
+def test_db_init__creates_tables(db):
+    with Cursor(db) as cursor:
+        cursor.execute("SELECT name FROM sqlite_master WHERE type='table'")
+        names = [row['name'] for row in cursor.fetchall()]
+    assert "commits" in names
+    assert "gerrit_patchsets" in names
+    assert "gerrit_changes" in names
+    assert "gerrit_duplicate_changes" in names
+
+
+def test_db_add_patchset__inserts_into_tables(db):
+    db.add_patchset(123, 1, "abc")
+    with Cursor(db) as cursor:
+        cursor.execute("SELECT * FROM gerrit_patchsets WHERE number=123")
+        change = cursor.fetchone()
+        assert change is not None
+        assert change["patchset"] == 1
+        assert change["commit_id"] == "abc"
+
+        cursor.execute("SELECT * FROM commits WHERE commit_id='abc'")
+        commit = cursor.fetchone()
+        assert commit is not None
+        assert commit["flags"] == 0
+
+
+def _dup_rows(db):
+    with Cursor(db) as cursor:
+        cursor.execute(
+            "SELECT number, change_id, canonical_number "
+            "FROM gerrit_duplicate_changes ORDER BY number"
+        )
+        return [tuple(row) for row in cursor.fetchall()]
+
+
+def _change_rows(db):
+    with Cursor(db) as cursor:
+        cursor.execute(
+            "SELECT number, current_patchset, change_id "
+            "FROM gerrit_changes ORDER BY number"
+        )
+        return [tuple(row) for row in cursor.fetchall()]
+
+
+def test_db_record_change__inserts_and_updates_canonical(db):
+    assert db.record_change(200, 1, "I200") is True
+    assert _change_rows(db) == [(200, 1, "I200")]
+
+    # A rescan of the same change refreshes the patchset in place.
+    assert db.record_change(200, 2, "I200") is True
+    assert _change_rows(db) == [(200, 2, "I200")]
+    assert _dup_rows(db) == []
+
+
+def test_db_record_change__sidebars_higher_numbered_duplicate(db):
+    db.record_change(300, 1, "Ishared")
+    assert db.record_change(305, 1, "Ishared") is False
+
+    assert _change_rows(db) == [(300, 1, "Ishared")]
+    assert _dup_rows(db) == [(305, "Ishared", 300)]
+
+
+def test_db_record_change__lower_number_takes_over_as_canonical(db):
+    # Changes arrive newest-first, as git-gerrit-sync scans them.
+    db.record_change(305, 1, "Ishared")
+    db.record_change(303, 1, "Ishared")
+    db.record_change(300, 1, "Ishared")
+
+    assert _change_rows(db) == [(300, 1, "Ishared")]
+    assert _dup_rows(db) == [(303, "Ishared", 300), (305, "Ishared", 300)]
+
+
+def test_db_record_change__canonical_stable_when_scanned_oldest_first(db):
+    db.record_change(300, 1, "Ishared")
+    db.record_change(303, 1, "Ishared")
+    db.record_change(305, 1, "Ishared")
+
+    assert _change_rows(db) == [(300, 1, "Ishared")]
+    assert _dup_rows(db) == [(303, "Ishared", 300), (305, "Ishared", 300)]
+
+
+def test_db_record_change__is_idempotent_across_rescans(db):
+    for _ in range(2):
+        db.record_change(305, 1, "Ishared")
+        db.record_change(303, 2, "Ishared")
+        db.record_change(300, 3, "Ishared")
+
+    assert _change_rows(db) == [(300, 3, "Ishared")]
+    assert _dup_rows(db) == [(303, "Ishared", 300), (305, "Ishared", 300)]
+
+
+def test_db_get_change__returns_canonical_only(db):
+    db.record_change(300, 1, "Ishared")
+    db.record_change(305, 2, "Ishared")
+
+    assert db.get_change("Ishared")["number"] == 300
+    assert db.get_change("Imissing") is None
+
+
+def test_db_count_duplicate_changes(db):
+    db.record_change(300, 1, "Ishared")
+    db.record_change(305, 1, "Ishared")
+    db.record_change(400, 1, "Iunique")
+
+    assert db.count_duplicate_changes() == 1
+
+
+def test_db_update_commit__updates_commit_row(db):
+    db.add_patchset(123, 1, "abc")
+    db.update_commit("abc", "I123", "def", 1)
+    with Cursor(db) as cursor:
+        cursor.execute("SELECT * FROM commits WHERE commit_id='abc'")
+        commit = cursor.fetchone()
+        assert commit is not None
+        assert commit["change_id"] == "I123"
+        assert commit["cherry_picked_from"] == "def"
+        assert commit["flags"] == 1
+
+
+def test_db_get_current_patchsets__returns_latest_patchsets(staged_db):
+    db = staged_db
+
+    # Test without filters
+    changes = list(db.get_current_patchsets())
+    assert len(changes) == 3
+    assert changes[0]["number"] == 103
+    assert changes[0]["current_patchset"] == 3
+    assert changes[0]["commit_id"] == "fff"
+    assert changes[0]["change_id"] == "I103"
+    assert changes[0]["cherry_picked_from"] == "ggg"
+    assert changes[0]["flags"] == 0
+
+    assert changes[1]["number"] == 102
+    assert changes[1]["current_patchset"] == 1
+    assert changes[1]["commit_id"] == "ccc"
+    assert changes[1]["change_id"] == "I102"
+    assert changes[1]["flags"] == 1
+
+    assert changes[2]["number"] == 101
+    assert changes[2]["current_patchset"] == 2
+    assert changes[2]["commit_id"] == "bbb"
+    assert changes[2]["change_id"] == "I101"
+    assert changes[2]["flags"] == 0
+
+    # Test with limit
+    changes = list(db.get_current_patchsets(limit=1))
+    assert len(changes) == 1
+    assert changes[0]["number"] == 103
+
+
+def test_db_get_current_patchset__returns_latest_patchset_by_number(staged_db):
+    db = staged_db
+    change = db.get_current_patchset_by_number(101)
+    assert change["number"] == 101
+    assert change["current_patchset"] == 2
+    assert change["commit_id"] == "bbb"
+    assert change["change_id"] == "I101"
+    assert change["flags"] == 0
+
+    change = db.get_current_patchset_by_number(102)
+    assert change["number"] == 102
+    assert change["current_patchset"] == 1
+    assert change["commit_id"] == "ccc"
+    assert change["change_id"] == "I102"
+    assert change["flags"] == 1
+
+    change = db.get_current_patchset_by_number(103)
+    assert change["number"] == 103
+    assert change["current_patchset"] == 3
+    assert change["commit_id"] == "fff"
+    assert change["change_id"] == "I103"
+    assert change["cherry_picked_from"] == "ggg"
+    assert change["flags"] == 0
+
+    change = db.get_current_patchset_by_number(999)
+    assert change is None

{git_gerrit-3.0.0 → git_gerrit-3.3.0}/tests/test_git.py

@@ -84,5 +84,7 @@ def test_write_hook(git):
 
 
 def test_change_id(git):
+    # The Change-Id is found even though the footer also contains non-trailer
+    # "FIXES" lines that defeat git's %(trailers) parser.
     got = git.change_id("0" * 40)
-    assert got == "I68fd140aab7e65bec1ac537d19de89f9d32443c1"
+    assert got == "Ibc6dab9f4a99d693ea03891ed7222fed9a07a85a"

git_gerrit-3.0.0/git_gerrit/__version__.py

@@ -1 +0,0 @@
-VERSION = "3.0.0"

git_gerrit-3.0.0/tests/test_db.py

@@ -1,121 +0,0 @@
-import pytest
-
-from git_gerrit.db import GitGerritDB, Cursor, SCHEMA_VERSION
-
-
-@pytest.fixture
-def db(mock_modules):
-    with GitGerritDB() as db:
-        yield db
-
-
-@pytest.fixture
-def staged_db(mock_modules):
-    with GitGerritDB() as db:
-        db.add_change(101, 1, "aaa")
-        db.add_change(101, 2, "bbb")
-        db.add_change(102, 1, "ccc")
-        db.add_change(103, 1, "ddd")
-        db.add_change(103, 2, "eee")
-        db.add_change(103, 3, "fff")
-        db.update_commit("bbb", "I101", None, 0)
-        db.update_commit("ccc", "I102", None, 1)
-        db.update_commit("fff", "I103", "ggg", 0)
-        yield db
-
-
-def test_db_get_schema_version__returns_current_schema_version(db):
-    assert db._get_schema_version() == SCHEMA_VERSION
-
-
-def test_db_init__creates_tables(db):
-    with Cursor(db) as cursor:
-        cursor.execute("SELECT name FROM sqlite_master WHERE type='table'")
-        names = [row['name'] for row in cursor.fetchall()]
-    assert len(names) != 0
-
-
-def test_db_add_change__inserts_into_tables(db):
-    db.add_change(123, 1, "abc")
-    with Cursor(db) as cursor:
-        cursor.execute("SELECT * FROM changes WHERE change_number=123")
-        change = cursor.fetchone()
-        assert change is not None
-        assert change["change_patchset"] == 1
-        assert change["change_commit_id"] == "abc"
-
-        cursor.execute("SELECT * FROM commits WHERE commit_id='abc'")
-        commit = cursor.fetchone()
-        assert commit is not None
-        assert commit["commit_flags"] == 0
-
-
-def test_db_update_commit__updates_commit_row(db):
-    db.add_change(123, 1, "abc")
-    db.update_commit("abc", "I123", "def", 1)
-    with Cursor(db) as cursor:
-        cursor.execute("SELECT * FROM commits WHERE commit_id='abc'")
-        commit = cursor.fetchone()
-        assert commit is not None
-        assert commit["commit_change_id"] == "I123"
-        assert commit["commit_picked_from"] == "def"
-        assert commit["commit_flags"] == 1
-
-
-def test_db_get_current_patchsets__returns_latest_patchsets(staged_db):
-    db = staged_db
-
-    # Test without filters
-    changes = list(db.get_current_patchsets())
-    assert len(changes) == 3
-    assert changes[0]["number"] == 103
-    assert changes[0]["current_patchset"] == 3
-    assert changes[0]["commit_id"] == "fff"
-    assert changes[0]["change_id"] == "I103"
-    assert changes[0]["cherry_picked_from"] == "ggg"
-    assert changes[0]["flags"] == 0
-
-    assert changes[1]["number"] == 102
-    assert changes[1]["current_patchset"] == 1
-    assert changes[1]["commit_id"] == "ccc"
-    assert changes[1]["change_id"] == "I102"
-    assert changes[1]["flags"] == 1
-
-    assert changes[2]["number"] == 101
-    assert changes[2]["current_patchset"] == 2
-    assert changes[2]["commit_id"] == "bbb"
-    assert changes[2]["change_id"] == "I101"
-    assert changes[2]["flags"] == 0
-
-    # Test with limit
-    changes = list(db.get_current_patchsets(limit=1))
-    assert len(changes) == 1
-    assert changes[0]["number"] == 103
-
-
-def test_db_get_current_patchset__returns_latest_patchset_by_number(staged_db):
-    db = staged_db
-    change = db.get_current_patchset_by_number(101)
-    assert change["number"] == 101
-    assert change["current_patchset"] == 2
-    assert change["commit_id"] == "bbb"
-    assert change["change_id"] == "I101"
-    assert change["flags"] == 0
-
-    change = db.get_current_patchset_by_number(102)
-    assert change["number"] == 102
-    assert change["current_patchset"] == 1
-    assert change["commit_id"] == "ccc"
-    assert change["change_id"] == "I102"
-    assert change["flags"] == 1
-
-    change = db.get_current_patchset_by_number(103)
-    assert change["number"] == 103
-    assert change["current_patchset"] == 3
-    assert change["commit_id"] == "fff"
-    assert change["change_id"] == "I103"
-    assert change["cherry_picked_from"] == "ggg"
-    assert change["flags"] == 0
-
-    change = db.get_current_patchset_by_number(999)
-    assert change is None