gerrit-clone 2.2.3__tar.gz → 2.3.0__tar.gz

{gerrit_clone-2.2.3 → gerrit_clone-2.3.0}/.pre-commit-config.yaml

@@ -4,21 +4,37 @@
 
 ci:
   autofix_prs: false
-  skip: [basedpyright, pytest, gha-workflow-linter]
+  skip:
+    - gha-workflow-linter
+    - aislop
+    - basedpyright
+    - pytest
   autofix_commit_msg: |
-    Chore: pre-commit autofixes
+    Chore: Pre-commit autofixes
 
     Signed-off-by: pre-commit-ci[bot] <pre-commit-ci@users.noreply.github.com>
   autoupdate_commit_msg: |
-    Chore: pre-commit autoupdate
+    Chore: Pre-commit autoupdate
 
     Signed-off-by: pre-commit-ci[bot] <pre-commit-ci@users.noreply.github.com>
 
+default_install_hook_types: [pre-commit, commit-msg]
+default_stages: [pre-commit]
+
 exclude: "^docs/conf.py"
 
 repos:
+  - repo: local
+    hooks:
+      - id: frozen-rev-is-a-release
+        name: frozen revs name a release
+        language: pygrep
+        # yamllint disable-line rule:line-length
+        entry: '^\s*rev:\s*\S+\s+#\s*frozen:(?!\s+v?[0-9]+(\.[0-9]+)*(-[0-9]+)?\s*$)'
+        files: '^\.pre-commit-config\.yaml$'
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # frozen: v6.0.0
+    rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c  # frozen: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: check-added-large-files
@@ -40,8 +56,14 @@ repos:
           - --branch=rc
           - --branch=production
 
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: 2ca41cc1372d1e939a6a879f18cdc19fc1cac1ce  # frozen: v8.30.0
+    hooks:
+      - id: gitleaks
+        always_run: true
+
   - repo: https://github.com/jorisroovers/gitlint
-    rev: acc9d9de6369b76d22cb4167029d2035e8730b98 # frozen: v0.19.1
+    rev: acc9d9de6369b76d22cb4167029d2035e8730b98  # frozen: v0.19.1
     hooks:
       - id: gitlint
 
@@ -52,16 +74,14 @@ repos:
         types: [yaml]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: aab412d509121cb5f7533134b7e67f9fab59c682  # frozen: v0.16.4
+    rev: f12be1ebaa5351c1fc76472de98db2c3446c8253  # frozen: v0.16.10
     hooks:
       - id: ruff
-        files: ^(scripts|tests|custom_components)/.+\.py$
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
-        files: ^(scripts|tests|custom_components)/.+\.py$
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 7ff8d35ae36a7d2b968f2f90b4c723e292e594ee  # frozen: v2.3.1
+    rev: 2834ec6639549dd6796205c8f011dedcd587288b  # frozen: v2.4.0
     hooks:
       - id: mypy
         additional_dependencies:
@@ -73,7 +93,7 @@ repos:
           - typer>=0.15.1
 
   - repo: https://github.com/btford/write-good
-    rev: ab66ce10136dfad5146e69e70f82a3efac8842c1 # frozen: v1.0.8
+    rev: ab66ce10136dfad5146e69e70f82a3efac8842c1  # frozen: v1.0.8
     hooks:
       - id: write-good
         files: "\\.(rst|md|markdown|mdown|mkdn)$"
@@ -95,32 +115,38 @@ repos:
     hooks:
       - id: reuse
 
-  # Replaces: https://github.com/rhysd/actionlint
-  # Permits actionlint to run both locally and with precommit.ci/GitHub
-  - repo: https://github.com/Mateusz-Grzelinski/actionlint-py
-    rev: c04ed26e40637cab1aa9879c693832a9c120fb20  # frozen: v1.7.12.24
+  - repo: https://github.com/kjanat/actionlint
+    rev: 2da2ceb4af2c7ecc48f5b9311d85080c3971b5f0  # frozen: v1.17.0
     hooks:
-      - id: actionlint
+      - id: actionlint-shellcheck
 
-  # Check for misspellings in documentation files
   - repo: https://github.com/codespell-project/codespell
     rev: 57b21406f092110c18776e39b0bda50d37c945c8  # frozen: v2.4.3
     hooks:
       - id: codespell
 
-  # Requires a mirror, primary repo lacks .pre-commit-hooks.yaml
   - repo: https://github.com/DetachHead/basedpyright-prek-mirror
-    rev: 3c94d276aa3005fa1f5a977946c9dc106135c083  # frozen: 1.39.10
+    rev: a11caebebdbf797e1e96611123db279b334a7675  # frozen: 1.40.2
     hooks:
       - id: basedpyright
 
   - repo: https://github.com/lfreleng-actions/gha-workflow-linter
-    rev: 42aa4db931ab4c9da0930ae5ca2259ab08da79cb  # frozen: v1.5.2
+    rev: b23b60e5884e985320a030e6114032152e2373cd  # frozen: v1.7.1
     hooks:
       - id: gha-workflow-linter
 
+  - repo: local
+    hooks:
+      - id: aislop
+        name: aislop
+        entry: aislop ci --human
+        language: node
+        additional_dependencies: ["aislop@0.13.1"]
+        pass_filenames: false
+        always_run: true
+
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: c4654a7e007c9619a5eb63c39a456572a0fa1851  # frozen: 0.38.0
+    rev: 4f85d46a92dc17713078e5de73f8a13190edf6fc  # frozen: 0.38.2
     hooks:
       - id: check-github-actions
       - id: check-github-workflows
@@ -134,7 +160,6 @@ repos:
           - yaml
       - id: check-readthedocs
 
-  # Run tests last to ensure all code changes from other hooks are tested
   - repo: local
     hooks:
       - id: pytest

{gerrit_clone-2.2.3 → gerrit_clone-2.3.0}/IMPLEMENTATION.md

@@ -253,11 +253,11 @@ Host gerrit.example.org
 
 ```python
 RetryPolicy(
-    max_attempts=3,      # Default retry count
-    base_delay=2.0,      # Initial delay in seconds
-    factor=2.0,          # Exponential backoff factor
-    max_delay=30.0,      # Upper delay cap
-    jitter=True          # Randomization enabled
+    max_attempts=3,  # Default retry count
+    base_delay=2.0,  # Initial delay in seconds
+    factor=2.0,  # Exponential backoff factor
+    max_delay=30.0,  # Upper delay cap
+    jitter=True,  # Randomization enabled
 )
 ```
 

gerrit_clone-2.3.0/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 [yyyy] [name of copyright owner]
+
+   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.

{gerrit_clone-2.2.3 → gerrit_clone-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gerrit-clone
-Version: 2.2.3
+Version: 2.3.0
 Summary: A multi-threaded CLI tool for bulk cloning repositories from Gerrit servers
 Project-URL: Homepage, https://github.com/lfreleng-actions/gerrit-clone-action
 Project-URL: Documentation, https://github.com/lfreleng-actions/gerrit-clone-action#readme
@@ -32,6 +32,7 @@ Requires-Dist: pyyaml<7.0.0,>=6.0.3
 Requires-Dist: rich<16.0.0,>=14.2.0
 Requires-Dist: typer<0.28.0,>=0.21.1
 Provides-Extra: dev
+Requires-Dist: git-filter-repo<3.0.0,>=2.47.0; extra == 'dev'
 Requires-Dist: pytest-asyncio<1.5.0,>=0.25.3; extra == 'dev'
 Requires-Dist: pytest-cov<8.0.0,>=6.3.0; extra == 'dev'
 Requires-Dist: pytest-mock<4.0.0,>=3.15.1; extra == 'dev'
@@ -225,6 +226,47 @@ a warning.
 
 ### Refresh Command Examples
 
+`refresh` finds both kinds of clone beneath the output path. A default
+(mirror) clone is a bare repository, so it has no branch to pull: refresh
+fetches every ref into it and prunes refs deleted upstream (unless
+`--no-prune`). The branch options (`--strategy`, `--auto-stash`, `--force`,
+`--force-hard`) apply to working-tree (`--no-mirror`) clones only. Refresh
+skips a bare repository with no fetch refspec that updates a ref, such as
+one made by `git clone --bare`, and says why: fetching it would update
+nothing. If the
+command finds no repositories at all, it says so and exits with status 1
+rather than reporting success.
+
+Content filtering (`--remove-files`, `--git-filter`, `--redact-secrets`) is a
+decision about a whole clone tree, and later runs keep to it. The first run
+that filters writes the decision to `.gerrit-clone/filter-policy.json` at the
+root of the tree. Every later `clone`, `refresh` or `mirror` in that tree
+applies it, even without the options: to repositories cloned later, to files
+that appear upstream later, and to a repository you delete and clone again.
+Options add to the decision; leaving one out never removes a filter. The file
+keeps each `--git-filter` token as a SHA-256 digest only, so a run must pass
+those tokens again. If a run lacks a project's tokens, `refresh` skips that
+project, `clone` exits with a filtering failure, and `mirror` aborts the
+whole batch before it pushes anything; each gives the number of tokens the
+project needs. A file the tool cannot read stops the run.
+
+Each repository also records which filters rewrote it. Fetching would force
+the original history back, filtered content included, so refresh copies each
+mirror it filters, fetches and filters the copy, and publishes its refs only
+when every step succeeds; a failure leaves the mirror unchanged. A filtered
+working copy (`--no-mirror`) always gets skipped: re-clone it to update it.
+Every remote of a filtered repository refuses pushes. A tree filtered before
+the tree-level file existed gains one from these per-repository records on
+its next run. Releases up to v2.2.4 recorded no filters at all, so refresh
+skips any repository they filtered, whatever filters you pass, and asks you
+to re-clone it, and `mirror --overwrite` leaves it out of the run rather
+than cloning or pushing it: delete it yourself, then clone it again with the
+filters it needs. The tool recognises one by the traces those releases left: the
+commit map a `git filter-repo` rewrite leaves in the git directory, or a
+branch tip committed by the file-removal fallback (`Remove filtered files
+for platform sync`).
+A `--dry-run` applies no content filters and records nothing.
+
 Refresh all repositories in the current directory:
 
 ```bash
@@ -884,8 +926,16 @@ export GITHUB_TOKEN=github_pat_your_token_here
 
 **With `--overwrite` flag**:
 
-- Removes and re-clones local repositories
-- Still skips existing GitHub repositories unless `--recreate` is also used
+- Removes and re-clones local repositories, then pushes each one
+  (`git push --mirror`) to its GitHub repository, existing ones included;
+  the tree's recorded content filters still apply first
+- Leaves out of the run any repository a release up to v2.2.4
+  content-filtered, and any directory holding one: those releases recorded
+  no filters to apply again, so the run neither re-clones nor pushes it,
+  `--recreate` leaves its GitHub repository alone, and the manifest lists
+  it as skipped
+- Without `--recreate`, reuses existing GitHub repositories rather than
+  deleting them
 
 **With both `--recreate` and `--overwrite`**:
 
@@ -1266,10 +1316,14 @@ The following SSH authentication options are available across all interfaces:
 | SSH Key    | `-i` (file path)       | `GERRIT_SSH_PRIVATE_KEY` | `ssh-private-key` (content) | Identity file  |
 | Host Check | `--strict-host`        | `GERRIT_STRICT_HOST`     | `strict-host`               | Key check      |
 
-> **Note:** The CLI flag `--ssh-identity-file` / `-i` expects a **file path**
-> to a private key on disk. The GitHub Action input `ssh-private-key` expects
-> the raw key **content** (loaded into an SSH agent). The legacy CLI alias
-> `--ssh-private-key` is still accepted for backward compatibility.
+> **Note:** The CLI flag `--ssh-identity-file` / `-i` and the
+> `GERRIT_SSH_PRIVATE_KEY` environment variable expect a **file path** to a
+> private key on disk. The GitHub Action input `ssh-private-key` expects the
+> raw key **content** (loaded into an SSH agent). Never place key content in
+> `GERRIT_SSH_PRIVATE_KEY`: the CLI rejects it, without echoing the value. In
+> workflows, hold the secret in a differently named variable and pipe it to
+> `ssh-add -`. The legacy CLI alias `--ssh-private-key` is still accepted for
+> backward compatibility.
 
 <!-- markdownlint-enable MD013 -->
 
@@ -1494,9 +1548,23 @@ cloned, while maintaining visibility into discovery issues between the two metho
 
 - Python 3.11+ (tested on 3.11, 3.12, 3.13, 3.14)
 - uv package manager (for development)
-- Git (for clone operations)
+- Git 2.31+ (for clone operations)
+- libcurl 7.58+ (for HTTPS token authentication)
 - SSH client (for authentication)
 
+> **Note:** Git 2.31 (March 2021) introduced the `GIT_CONFIG_COUNT` /
+> `GIT_CONFIG_KEY_*` / `GIT_CONFIG_VALUE_*` environment variables. Both the
+> clone and mirror-push paths use them to pass a GitHub token to `git`, so the
+> token stays out of the command line and out of the host's process listing.
+> Older Git releases ignore those variables, and HTTPS token authentication
+> will fail.
+>
+> The token travels as an `Authorization` header scoped to the source host.
+> Git hands that to libcurl as a custom header, and libcurl before 7.58
+> (January 2018, CVE-2018-1000007) forwards a custom `Authorization` to a
+> different host across a redirect. Every current distribution ships a later
+> release; the floor matters only for a long-lived self-hosted runner.
+
 ### Setup
 
 ```bash

{gerrit_clone-2.2.3 → gerrit_clone-2.3.0}/README.md

@@ -184,6 +184,47 @@ a warning.
 
 ### Refresh Command Examples
 
+`refresh` finds both kinds of clone beneath the output path. A default
+(mirror) clone is a bare repository, so it has no branch to pull: refresh
+fetches every ref into it and prunes refs deleted upstream (unless
+`--no-prune`). The branch options (`--strategy`, `--auto-stash`, `--force`,
+`--force-hard`) apply to working-tree (`--no-mirror`) clones only. Refresh
+skips a bare repository with no fetch refspec that updates a ref, such as
+one made by `git clone --bare`, and says why: fetching it would update
+nothing. If the
+command finds no repositories at all, it says so and exits with status 1
+rather than reporting success.
+
+Content filtering (`--remove-files`, `--git-filter`, `--redact-secrets`) is a
+decision about a whole clone tree, and later runs keep to it. The first run
+that filters writes the decision to `.gerrit-clone/filter-policy.json` at the
+root of the tree. Every later `clone`, `refresh` or `mirror` in that tree
+applies it, even without the options: to repositories cloned later, to files
+that appear upstream later, and to a repository you delete and clone again.
+Options add to the decision; leaving one out never removes a filter. The file
+keeps each `--git-filter` token as a SHA-256 digest only, so a run must pass
+those tokens again. If a run lacks a project's tokens, `refresh` skips that
+project, `clone` exits with a filtering failure, and `mirror` aborts the
+whole batch before it pushes anything; each gives the number of tokens the
+project needs. A file the tool cannot read stops the run.
+
+Each repository also records which filters rewrote it. Fetching would force
+the original history back, filtered content included, so refresh copies each
+mirror it filters, fetches and filters the copy, and publishes its refs only
+when every step succeeds; a failure leaves the mirror unchanged. A filtered
+working copy (`--no-mirror`) always gets skipped: re-clone it to update it.
+Every remote of a filtered repository refuses pushes. A tree filtered before
+the tree-level file existed gains one from these per-repository records on
+its next run. Releases up to v2.2.4 recorded no filters at all, so refresh
+skips any repository they filtered, whatever filters you pass, and asks you
+to re-clone it, and `mirror --overwrite` leaves it out of the run rather
+than cloning or pushing it: delete it yourself, then clone it again with the
+filters it needs. The tool recognises one by the traces those releases left: the
+commit map a `git filter-repo` rewrite leaves in the git directory, or a
+branch tip committed by the file-removal fallback (`Remove filtered files
+for platform sync`).
+A `--dry-run` applies no content filters and records nothing.
+
 Refresh all repositories in the current directory:
 
 ```bash
@@ -843,8 +884,16 @@ export GITHUB_TOKEN=github_pat_your_token_here
 
 **With `--overwrite` flag**:
 
-- Removes and re-clones local repositories
-- Still skips existing GitHub repositories unless `--recreate` is also used
+- Removes and re-clones local repositories, then pushes each one
+  (`git push --mirror`) to its GitHub repository, existing ones included;
+  the tree's recorded content filters still apply first
+- Leaves out of the run any repository a release up to v2.2.4
+  content-filtered, and any directory holding one: those releases recorded
+  no filters to apply again, so the run neither re-clones nor pushes it,
+  `--recreate` leaves its GitHub repository alone, and the manifest lists
+  it as skipped
+- Without `--recreate`, reuses existing GitHub repositories rather than
+  deleting them
 
 **With both `--recreate` and `--overwrite`**:
 
@@ -1225,10 +1274,14 @@ The following SSH authentication options are available across all interfaces:
 | SSH Key    | `-i` (file path)       | `GERRIT_SSH_PRIVATE_KEY` | `ssh-private-key` (content) | Identity file  |
 | Host Check | `--strict-host`        | `GERRIT_STRICT_HOST`     | `strict-host`               | Key check      |
 
-> **Note:** The CLI flag `--ssh-identity-file` / `-i` expects a **file path**
-> to a private key on disk. The GitHub Action input `ssh-private-key` expects
-> the raw key **content** (loaded into an SSH agent). The legacy CLI alias
-> `--ssh-private-key` is still accepted for backward compatibility.
+> **Note:** The CLI flag `--ssh-identity-file` / `-i` and the
+> `GERRIT_SSH_PRIVATE_KEY` environment variable expect a **file path** to a
+> private key on disk. The GitHub Action input `ssh-private-key` expects the
+> raw key **content** (loaded into an SSH agent). Never place key content in
+> `GERRIT_SSH_PRIVATE_KEY`: the CLI rejects it, without echoing the value. In
+> workflows, hold the secret in a differently named variable and pipe it to
+> `ssh-add -`. The legacy CLI alias `--ssh-private-key` is still accepted for
+> backward compatibility.
 
 <!-- markdownlint-enable MD013 -->
 
@@ -1453,9 +1506,23 @@ cloned, while maintaining visibility into discovery issues between the two metho
 
 - Python 3.11+ (tested on 3.11, 3.12, 3.13, 3.14)
 - uv package manager (for development)
-- Git (for clone operations)
+- Git 2.31+ (for clone operations)
+- libcurl 7.58+ (for HTTPS token authentication)
 - SSH client (for authentication)
 
+> **Note:** Git 2.31 (March 2021) introduced the `GIT_CONFIG_COUNT` /
+> `GIT_CONFIG_KEY_*` / `GIT_CONFIG_VALUE_*` environment variables. Both the
+> clone and mirror-push paths use them to pass a GitHub token to `git`, so the
+> token stays out of the command line and out of the host's process listing.
+> Older Git releases ignore those variables, and HTTPS token authentication
+> will fail.
+>
+> The token travels as an `Authorization` header scoped to the source host.
+> Git hands that to libcurl as a custom header, and libcurl before 7.58
+> (January 2018, CVE-2018-1000007) forwards a custom `Authorization` to a
+> different host across a redirect. Every current distribution ships a later
+> release; the floor matters only for a long-lived self-hosted runner.
+
 ### Setup
 
 ```bash

{gerrit_clone-2.2.3 → gerrit_clone-2.3.0}/pyproject.toml

@@ -2,7 +2,12 @@
 # SPDX-FileCopyrightText: 2025 The Linux Foundation
 
 [build-system]
-requires = ["hatchling", "hatch-vcs"]
+# PEP 517 builds run in an isolated environment that uv.lock does not
+# govern, so these are resolved fresh from PyPI on every build --
+# including the release build.  Bounding them stops that resolution
+# crossing a major release of the build backend unnoticed.  The floors
+# match the dev dependency-group entries Dependabot maintains.
+requires = ["hatchling>=1.27.0,<2.0.0", "hatch-vcs>=0.5.0,<1.0.0"]
 build-backend = "hatchling.build"
 
 [project]
@@ -53,6 +58,12 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
+    # Supplies the ``git-filter-repo`` executable that content filtering
+    # shells out to.  Listed here as well as in the dev dependency group
+    # because CI's test job installs this extra (``.[test,dev]``) and
+    # never reads the group: without it the history-rewriting tests
+    # cannot run there.
+    "git-filter-repo>=2.47.0,<3.0.0",
     "pytest>=8.4.2,<10.0.0",
     "pytest-cov>=6.3.0,<8.0.0",
     "pytest-mock>=3.15.1,<4.0.0",
@@ -283,6 +294,15 @@ asyncio_default_fixture_loop_scope = "function"
 
 # Coverage configuration
 [tool.coverage.run]
+# Keep the transient coverage database out of the working tree.
+# coverage.py resolves a relative data_file against the current
+# directory, so the default '.coverage' lands wherever pytest runs and
+# can be picked up by tests that inspect on-disk content. TEMP is
+# set on Windows, where /tmp does not exist; elsewhere it is normally
+# unset and the /tmp fallback applies. An explicit value also
+# satisfies python-test-action's data_file configuration check.
+# COVERAGE_FILE (env) still takes precedence when set.
+data_file = "${TEMP-/tmp}/.coverage.gerrit-clone-action"
 source = ["gerrit_clone"]
 branch = true
 omit = [
@@ -355,6 +375,21 @@ reportIncompatibleVariableOverride = "error"
 reportOverlappingOverload = "error"
 reportUnsupportedDunderAll = "error"
 
+[tool.uv]
+# `[build-system] requires` bounds this project's own build environment
+# only.  These constraints apply to every isolated build environment uv
+# creates, so a dependency that has to be built from an sdist is held to
+# the same bounds.
+#
+# Deliberately ranges rather than `==` pins: an exact pin would have to
+# be bumped by hand before a new Python release could build at all,
+# whereas a major-version cap still blocks the breaking change without
+# blocking routine patches.
+build-constraint-dependencies = [
+    "hatchling>=1.27.0,<2.0.0",
+    "hatch-vcs>=0.5.0,<1.0.0",
+]
+
 [dependency-groups]
 dev = [
     # Supplies the ``git-filter-repo`` executable that