PyPI - github-backup - Versions diffs - 0.61.4__tar.gz → 0.62.0__tar.gz - Mend

github-backup 0.61.4tar.gz → 0.62.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

{github_backup-0.61.4 → github_backup-0.62.0}/CHANGES.rst RENAMED Viewed

@@ -1,9 +1,173 @@
 Changelog
 =========
-0.61.4 (2026-02-16)
+0.62.0 (2026-04-29)
 -------------------
 ------------------------
+- Skip checkpoint-equal incremental items. [Duncan Ogilvie]
+- Avoid redundant release asset list requests. [Duncan Ogilvie]
+- Reduce unnecessary pull requests with incremental fetching. [Duncan
+  Ogilvie]
+- Implement per-resource last_update timestamps. [Duncan Ogilvie]
+  Closes #62
+- Add support for pull request reviews. [Duncan Ogilvie]
+  Closes #124
+- Add support for discussions. [Duncan Ogilvie]
+  Closes #290
+- Add --token-from-gh authentication option. [Duncan Ogilvie]
+- Chore(deps): bump pytest in the python-packages group.
+  [dependabot[bot]]
+  Bumps the python-packages group with 1 update: [pytest](https://github.com/pytest-dev/pytest).
+  Updates `pytest` from 9.0.2 to 9.0.3
+  - [Release notes](https://github.com/pytest-dev/pytest/releases)
+  - [Changelog](https://github.com/pytest-dev/pytest/blob/main/CHANGELOG.rst)
+  - [Commits](https://github.com/pytest-dev/pytest/compare/9.0.2...9.0.3)
+  ---
+  updated-dependencies:
+  - dependency-name: pytest
+    dependency-version: 9.0.3
+    dependency-type: direct:production
+    update-type: version-update:semver-patch
+    dependency-group: python-packages
+  ...
+- Chore(deps): bump black in the python-packages group.
+  [dependabot[bot]]
+  Bumps the python-packages group with 1 update: [black](https://github.com/psf/black).
+  Updates `black` from 26.3.0 to 26.3.1
+  - [Release notes](https://github.com/psf/black/releases)
+  - [Changelog](https://github.com/psf/black/blob/main/CHANGES.md)
+  - [Commits](https://github.com/psf/black/compare/26.3.0...26.3.1)
+  ---
+  updated-dependencies:
+  - dependency-name: black
+    dependency-version: 26.3.1
+    dependency-type: direct:production
+    update-type: version-update:semver-patch
+    dependency-group: python-packages
+  ...
+- Chore(deps): bump docker/login-action from 3 to 4. [dependabot[bot]]
+  Bumps [docker/login-action](https://github.com/docker/login-action) from 3 to 4.
+  - [Release notes](https://github.com/docker/login-action/releases)
+  - [Commits](https://github.com/docker/login-action/compare/v3...v4)
+  ---
+  updated-dependencies:
+  - dependency-name: docker/login-action
+    dependency-version: '4'
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+- Chore(deps): bump docker/setup-qemu-action from 3 to 4.
+  [dependabot[bot]]
+  Bumps [docker/setup-qemu-action](https://github.com/docker/setup-qemu-action) from 3 to 4.
+  - [Release notes](https://github.com/docker/setup-qemu-action/releases)
+  - [Commits](https://github.com/docker/setup-qemu-action/compare/v3...v4)
+  ---
+  updated-dependencies:
+  - dependency-name: docker/setup-qemu-action
+    dependency-version: '4'
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+- Chore(deps): bump docker/build-push-action from 6 to 7.
+  [dependabot[bot]]
+  Bumps [docker/build-push-action](https://github.com/docker/build-push-action) from 6 to 7.
+  - [Release notes](https://github.com/docker/build-push-action/releases)
+  - [Commits](https://github.com/docker/build-push-action/compare/v6...v7)
+  ---
+  updated-dependencies:
+  - dependency-name: docker/build-push-action
+    dependency-version: '7'
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+- Chore(deps): bump docker/setup-buildx-action from 3 to 4.
+  [dependabot[bot]]
+  Bumps [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) from 3 to 4.
+  - [Release notes](https://github.com/docker/setup-buildx-action/releases)
+  - [Commits](https://github.com/docker/setup-buildx-action/compare/v3...v4)
+  ---
+  updated-dependencies:
+  - dependency-name: docker/setup-buildx-action
+    dependency-version: '4'
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+- Chore(deps): bump docker/metadata-action from 5 to 6.
+  [dependabot[bot]]
+  Bumps [docker/metadata-action](https://github.com/docker/metadata-action) from 5 to 6.
+  - [Release notes](https://github.com/docker/metadata-action/releases)
+  - [Commits](https://github.com/docker/metadata-action/compare/v5...v6)
+  ---
+  updated-dependencies:
+  - dependency-name: docker/metadata-action
+    dependency-version: '6'
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+- Chore(deps): bump the python-packages group with 2 updates.
+  [dependabot[bot]]
+  Bumps the python-packages group with 2 updates: [black](https://github.com/psf/black) and [setuptools](https://github.com/pypa/setuptools).
+  Updates `black` from 26.1.0 to 26.3.0
+  - [Release notes](https://github.com/psf/black/releases)
+  - [Changelog](https://github.com/psf/black/blob/main/CHANGES.md)
+  - [Commits](https://github.com/psf/black/compare/26.1.0...26.3.0)
+  Updates `setuptools` from 82.0.0 to 82.0.1
+  - [Release notes](https://github.com/pypa/setuptools/releases)
+  - [Changelog](https://github.com/pypa/setuptools/blob/main/NEWS.rst)
+  - [Commits](https://github.com/pypa/setuptools/compare/v82.0.0...v82.0.1)
+  ---
+  updated-dependencies:
+  - dependency-name: black
+    dependency-version: 26.3.0
+    dependency-type: direct:production
+    update-type: version-update:semver-minor
+    dependency-group: python-packages
+  - dependency-name: setuptools
+    dependency-version: 82.0.1
+    dependency-type: direct:production
+    update-type: version-update:semver-patch
+    dependency-group: python-packages
+  ...
+0.61.5 (2026-02-18)
+-------------------
+- Fix empty repository crash due to None timestamp comparison (#489)
+  [Rodos]
+  Empty repositories have None for pushed_at/updated_at, causing a
+  TypeError when compared to the last_update string. Use .get() with
+  truthiness check to skip None timestamps in incremental tracking.
+0.61.4 (2026-02-16)
+-------------------
 - Fix HTTP 451 DMCA and 403 TOS handling regression (#487) [Rodos]
   The DMCA handling added in PR #454 had a bug: make_request_with_retry()

{github_backup-0.61.4/github_backup.egg-info → github_backup-0.62.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-backup
-Version: 0.61.4
+Version: 0.62.0
 Summary: backup a github user or organization
 Home-page: http://github.com/josegonzalez/python-github-backup
 Author: Jose Diaz-Gonzalez
@@ -34,7 +34,7 @@ github-backup
 |PyPI| |Python Versions|
-The package can be used to backup an *entire* `Github <https://github.com/>`_ organization, repository or user account, including starred repos, issues and wikis in the most appropriate format (clones for wikis, json files for issues).
+The package can be used to backup an *entire* `Github <https://github.com/>`_ organization, repository or user account, including starred repos, issues, discussions and wikis in the most appropriate format (clones for wikis, json files for issues and discussions).
 Requirements
 ============
@@ -66,16 +66,18 @@ Show the CLI help output::
 CLI Help output::
-    github-backup [-h] [-t TOKEN_CLASSIC] [-f TOKEN_FINE] [-q] [--as-app]
-                  [-o OUTPUT_DIRECTORY] [-l LOG_LEVEL] [-i]
+    github-backup [-h] [-t TOKEN_CLASSIC] [-f TOKEN_FINE] [--token-from-gh]
+                  [-q] [--as-app] [-o OUTPUT_DIRECTORY] [-l LOG_LEVEL] [-i]
                   [--incremental-by-files]
                   [--starred] [--all-starred] [--starred-skip-size-over MB]
                   [--watched] [--followers] [--following] [--all]
                   [--issues] [--issue-comments] [--issue-events] [--pulls]
-                  [--pull-comments] [--pull-commits] [--pull-details]
+                  [--pull-comments] [--pull-reviews] [--pull-commits]
+                  [--pull-details]
                   [--labels] [--hooks] [--milestones] [--security-advisories]
-                  [--repositories] [--bare] [--no-prune] [--lfs] [--wikis]
-                  [--gists] [--starred-gists] [--skip-archived] [--skip-existing]
+                  [--discussions] [--repositories] [--bare] [--no-prune]
+                  [--lfs] [--wikis] [--gists] [--starred-gists]
+                  [--skip-archived] [--skip-existing]
                   [-L [LANGUAGES ...]] [-N NAME_REGEX] [-H GITHUB_HOST]
                   [-O] [-R REPOSITORY] [-P] [-F] [--prefer-ssh] [-v]
                   [--keychain-name OSX_KEYCHAIN_ITEM_NAME]
@@ -101,6 +103,7 @@ CLI Help output::
       -f, --token-fine TOKEN_FINE
                             fine-grained personal access token (github_pat_....),
                             or path to token (file://...)
+      --token-from-gh       read token from GitHub CLI (gh auth token)
       -q, --quiet           supress log messages less severe than warning, e.g.
                             info
       --as-app              authenticate as github app instead of as a user.
@@ -125,6 +128,7 @@ CLI Help output::
       --issue-events        include issue events in backup
       --pulls               include pull requests in backup
       --pull-comments       include pull request review comments in backup
+      --pull-reviews        include pull request reviews in backup
       --pull-commits        include pull request commits in backup
       --pull-details        include more pull request details in backup [*]
       --labels              include labels in backup
@@ -133,6 +137,7 @@ CLI Help output::
       --milestones          include milestones in backup
       --security-advisories
                             include security advisories in backup
+      --discussions         include discussions in backup
       --repositories        include repository clone in backup
       --bare                clone bare repositories
       --no-prune            disable prune option for git fetch
@@ -173,8 +178,8 @@ CLI Help output::
                             applies if including releases
       --skip-assets-on [SKIP_ASSETS_ON ...]
                             skip asset downloads for these repositories
-      --attachments         download user-attachments from issues and pull
-                            requests
+      --attachments         download user-attachments from issues, pull requests,
+                            and discussions
       --throttle-limit THROTTLE_LIMIT
                             start throttling of GitHub API requests after this
                             amount of API requests remain
@@ -201,6 +206,8 @@ The positional argument ``USER`` specifies the user or organization account you
 **Classic tokens** (``-t TOKEN``) are `slightly less secure <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic>`_ as they provide very coarse-grained permissions.
+If you already authenticate with the `GitHub CLI <https://cli.github.com/>`_, you can use ``--token-from-gh`` to read the token with ``gh auth token`` instead of passing a token directly. This avoids placing the token in shell history or process arguments. When ``--github-host`` is set, the token is read with ``gh auth token --hostname HOST``.
 Fine Tokens
 ~~~~~~~~~~~
@@ -211,7 +218,7 @@ Customise the permissions for your use case, but for a personal account full bac
 **User permissions**: Read access to followers, starring, and watching.
-**Repository permissions**: Read access to contents, issues, metadata, pull requests, and webhooks.
+**Repository permissions**: Read access to contents, discussions, issues, metadata, pull requests, and webhooks.
 GitHub Apps
@@ -292,9 +299,9 @@ LFS objects are fetched for all refs, not just the current checkout, ensuring a
 About Attachments
 -----------------
-When you use the ``--attachments`` option with ``--issues`` or ``--pulls``, the tool will download user-uploaded attachments (images, videos, documents, etc.) from issue and pull request descriptions and comments. In some circumstances attachments contain valuable data related to the topic, and without their backup important information or context might be lost inadvertently.
+When you use the ``--attachments`` option with ``--issues``, ``--pulls`` or ``--discussions``, the tool will download user-uploaded attachments (images, videos, documents, etc.) from issue, pull request and discussion descriptions and comments. In some circumstances attachments contain valuable data related to the topic, and without their backup important information or context might be lost inadvertently.
-Attachments are saved to ``issues/attachments/{issue_number}/`` and ``pulls/attachments/{pull_number}/`` directories, where ``{issue_number}`` is the GitHub issue number (e.g., issue #123 saves to ``issues/attachments/123/``). Each attachment directory contains:
+Attachments are saved to ``issues/attachments/{issue_number}/``, ``pulls/attachments/{pull_number}/`` and ``discussions/attachments/{discussion_number}/`` directories, where ``{issue_number}`` is the GitHub issue number (e.g., issue #123 saves to ``issues/attachments/123/``). Each attachment directory contains:
 - The downloaded attachment files (named by their GitHub identifier with appropriate file extensions)
 - If multiple attachments have the same filename, conflicts are resolved with numeric suffixes (e.g., ``report.pdf``, ``report_1.pdf``, ``report_2.pdf``)
@@ -314,6 +321,16 @@ The tool automatically extracts file extensions from HTTP headers to ensure file
 **Fine-grained token limitation:** Due to a GitHub platform limitation, fine-grained personal access tokens (``github_pat_...``) cannot download attachments from private repositories directly. This affects both ``/assets/`` (images) and ``/files/`` (documents) URLs. The tool implements a workaround for image attachments using GitHub's Markdown API, which converts URLs to temporary JWT-signed URLs that can be downloaded. However, this workaround only works for images - document attachments (PDFs, text files, etc.) will fail with 404 errors when using fine-grained tokens on private repos. For full attachment support on private repositories, use a classic token (``-t``) instead of a fine-grained token (``-f``). See `#477 <https://github.com/josegonzalez/python-github-backup/issues/477>`_ for details.
+About Discussions
+-----------------
+GitHub Discussions are backed up with GitHub's GraphQL API because the REST API does not expose discussions. Use ``--discussions`` to save each discussion as JSON under ``repositories/{repo}/discussions/{number}.json``. Discussion backups include the discussion body and metadata, category information, comments, and comment replies.
+``--discussions`` is included in ``--all``. Unlike most REST API-backed resources, discussions require authentication because GitHub's GraphQL API requires a token. Fine-grained personal access tokens and GitHub Apps need read access to the repository's Discussions permission.
+Incremental backups use a per-repository checkpoint at ``repositories/{repo}/discussions/last_update`` based on discussion ``updatedAt`` timestamps. This is separate from the repository-level ``last_update`` file so discussion activity is not missed if the repository's own update timestamp does not change. If you enable ``--discussions`` on an existing incremental backup, the first run performs a full discussions backup for each repository and creates the discussions checkpoint for future runs.
 About security advisories
 -------------------------
@@ -355,12 +372,24 @@ For finer control, avoid using ``--assets`` with starred repos, or use ``--skip-
 Alternatively, consider just storing links to starred repos in JSON format with ``--starred``.
+About pull request reviews
+--------------------------
+Use ``--pull-reviews`` with ``--pulls`` to include GitHub pull request review metadata under each pull request's ``review_data`` key. Reviews are separate from review comments: ``--pull-comments`` backs up inline review comments via ``comment_data`` and regular PR conversation comments via ``comment_regular_data``, while ``--pull-reviews`` backs up review state, submitted time, commit ID, and the top-level review body.
+``--pull-reviews`` is included in ``--all``. Incremental backups use a per-repository checkpoint at ``repositories/{repo}/pulls/reviews_last_update``. If ``--pull-reviews`` is enabled on an existing incremental backup, the first run performs a one-time backfill for pull request reviews so older PRs are not skipped by the existing pull request checkpoint. Existing ``comment_data``, ``comment_regular_data`` and ``commit_data`` fields are preserved when only review data is being added.
 Incremental Backup
 ------------------
-Using (``-i, --incremental``) will only request new data from the API **since the last run (successful or not)**. e.g. only request issues from the API since the last run.
+Using (``-i, --incremental``) will only request new data from the API **since the last successful resource backup**. e.g. only request issues from the API since the last issue backup for that repository.
+Incremental checkpoints for issue and pull request API backups are stored per resource in that repository's backup directory (for example ``repositories/{repo}/issues/last_update``, ``repositories/{repo}/pulls/last_update`` or ``starred/{owner}/{repo}/pulls/last_update``). Older versions stored a single global ``last_update`` file in the output directory root. During migration, the legacy global checkpoint is used as a fallback only for resource directories that already contain backup data but do not yet have their own checkpoint. New repositories or newly enabled resources with no existing data get a full backup instead of inheriting an unrelated global checkpoint.
+After all existing issue and pull request resource directories have per-resource checkpoints, the legacy global ``last_update`` file is removed automatically.
-This means any blocking errors on previous runs can cause a large amount of missing data in backups.
+This means any blocking errors on previous runs can cause missing data in backups for the affected repository resource.
 Using (``--incremental-by-files``) will request new data from the API **based on when the file was modified on filesystem**. e.g. if you modify the file yourself you may miss something.
@@ -373,7 +402,7 @@ Known blocking errors
 Some errors will block the backup run by exiting the script. e.g. receiving a 403 Forbidden error from the Github API.
-If the incremental argument is used, this will result in the next backup only requesting API data since the last blocked/failed run. Potentially causing unexpected large amounts of missing data.
+If the incremental argument is used, per-resource checkpoints are only advanced after that resource's backup work completes. A blocking error can still abort the overall run, but repositories and resources that were not processed will keep their previous checkpoints.
 It's therefore recommended to only use the incremental argument if the output/result is being actively monitored, or complimented with periodic full non-incremental runs, to avoid unexpected missing data in a regular backup runs.
@@ -446,14 +475,14 @@ Quietly and incrementally backup useful Github user data (public and private rep
     export FINE_ACCESS_TOKEN=SOME-GITHUB-TOKEN
     GH_USER=YOUR-GITHUB-USER
-    github-backup -f $FINE_ACCESS_TOKEN --prefer-ssh -o ~/github-backup/ -l error -P -i --all-starred --starred --watched --followers --following --issues --issue-comments --issue-events --pulls --pull-comments --pull-commits --labels --milestones --security-advisories --repositories --wikis --releases --assets --attachments --pull-details --gists --starred-gists $GH_USER
+    github-backup -f $FINE_ACCESS_TOKEN --prefer-ssh -o ~/github-backup/ -l error -P -i --all-starred --starred --watched --followers --following --issues --issue-comments --issue-events --pulls --pull-comments --pull-reviews --pull-commits --labels --milestones --security-advisories --discussions --repositories --wikis --releases --assets --attachments --pull-details --gists --starred-gists $GH_USER
 Debug an error/block or incomplete backup into a temporary directory. Omit "incremental" to fill a previous incomplete backup. ::
     export FINE_ACCESS_TOKEN=SOME-GITHUB-TOKEN
     GH_USER=YOUR-GITHUB-USER
-    github-backup -f $FINE_ACCESS_TOKEN -o /tmp/github-backup/ -l debug -P --all-starred --starred --watched --followers --following --issues --issue-comments --issue-events --pulls --pull-comments --pull-commits --labels --milestones --repositories --wikis --releases --assets --pull-details --gists --starred-gists $GH_USER
+    github-backup -f $FINE_ACCESS_TOKEN -o /tmp/github-backup/ -l debug -P --all-starred --starred --watched --followers --following --issues --issue-comments --issue-events --pulls --pull-comments --pull-reviews --pull-commits --labels --milestones --discussions --repositories --wikis --releases --assets --pull-details --gists --starred-gists $GH_USER
 Pipe a token from stdin to avoid storing it in environment variables or command history (Unix-like systems only)::
@@ -469,7 +498,7 @@ This tool creates backups only, there is no inbuilt restore command.
     cd /tmp/white-house/repositories/petitions/repository
     git push --mirror git@github.com:WhiteHouse/petitions.git
-**Issues, pull requests, comments, and other metadata** are saved as JSON files for archival purposes. The GitHub API does not support recreating this data faithfully, creating issues via the API has limitations:
+**Issues, pull requests, discussions, comments, and other metadata** are saved as JSON files for archival purposes. The GitHub API does not support recreating this data faithfully, creating issues via the API has limitations:
 - New issue/PR numbers are assigned (original numbers cannot be set)
 - Timestamps reflect creation time (original dates cannot be set)

{github_backup-0.61.4 → github_backup-0.62.0}/README RENAMED Viewed

@@ -4,7 +4,7 @@ github-backup
 |PyPI| |Python Versions|
-The package can be used to backup an *entire* `Github <https://github.com/>`_ organization, repository or user account, including starred repos, issues and wikis in the most appropriate format (clones for wikis, json files for issues).
+The package can be used to backup an *entire* `Github <https://github.com/>`_ organization, repository or user account, including starred repos, issues, discussions and wikis in the most appropriate format (clones for wikis, json files for issues and discussions).
 Requirements
 ============
@@ -36,16 +36,18 @@ Show the CLI help output::
 CLI Help output::
-    github-backup [-h] [-t TOKEN_CLASSIC] [-f TOKEN_FINE] [-q] [--as-app]
-                  [-o OUTPUT_DIRECTORY] [-l LOG_LEVEL] [-i]
+    github-backup [-h] [-t TOKEN_CLASSIC] [-f TOKEN_FINE] [--token-from-gh]
+                  [-q] [--as-app] [-o OUTPUT_DIRECTORY] [-l LOG_LEVEL] [-i]
                   [--incremental-by-files]
                   [--starred] [--all-starred] [--starred-skip-size-over MB]
                   [--watched] [--followers] [--following] [--all]
                   [--issues] [--issue-comments] [--issue-events] [--pulls]
-                  [--pull-comments] [--pull-commits] [--pull-details]
+                  [--pull-comments] [--pull-reviews] [--pull-commits]
+                  [--pull-details]
                   [--labels] [--hooks] [--milestones] [--security-advisories]
-                  [--repositories] [--bare] [--no-prune] [--lfs] [--wikis]
-                  [--gists] [--starred-gists] [--skip-archived] [--skip-existing]
+                  [--discussions] [--repositories] [--bare] [--no-prune]
+                  [--lfs] [--wikis] [--gists] [--starred-gists]
+                  [--skip-archived] [--skip-existing]
                   [-L [LANGUAGES ...]] [-N NAME_REGEX] [-H GITHUB_HOST]
                   [-O] [-R REPOSITORY] [-P] [-F] [--prefer-ssh] [-v]
                   [--keychain-name OSX_KEYCHAIN_ITEM_NAME]
@@ -71,6 +73,7 @@ CLI Help output::
       -f, --token-fine TOKEN_FINE
                             fine-grained personal access token (github_pat_....),
                             or path to token (file://...)
+      --token-from-gh       read token from GitHub CLI (gh auth token)
       -q, --quiet           supress log messages less severe than warning, e.g.
                             info
       --as-app              authenticate as github app instead of as a user.
@@ -95,6 +98,7 @@ CLI Help output::
       --issue-events        include issue events in backup
       --pulls               include pull requests in backup
       --pull-comments       include pull request review comments in backup
+      --pull-reviews        include pull request reviews in backup
       --pull-commits        include pull request commits in backup
       --pull-details        include more pull request details in backup [*]
       --labels              include labels in backup
@@ -103,6 +107,7 @@ CLI Help output::
       --milestones          include milestones in backup
       --security-advisories
                             include security advisories in backup
+      --discussions         include discussions in backup
       --repositories        include repository clone in backup
       --bare                clone bare repositories
       --no-prune            disable prune option for git fetch
@@ -143,8 +148,8 @@ CLI Help output::
                             applies if including releases
       --skip-assets-on [SKIP_ASSETS_ON ...]
                             skip asset downloads for these repositories
-      --attachments         download user-attachments from issues and pull
-                            requests
+      --attachments         download user-attachments from issues, pull requests,
+                            and discussions
       --throttle-limit THROTTLE_LIMIT
                             start throttling of GitHub API requests after this
                             amount of API requests remain
@@ -171,6 +176,8 @@ The positional argument ``USER`` specifies the user or organization account you
 **Classic tokens** (``-t TOKEN``) are `slightly less secure <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic>`_ as they provide very coarse-grained permissions.
+If you already authenticate with the `GitHub CLI <https://cli.github.com/>`_, you can use ``--token-from-gh`` to read the token with ``gh auth token`` instead of passing a token directly. This avoids placing the token in shell history or process arguments. When ``--github-host`` is set, the token is read with ``gh auth token --hostname HOST``.
 Fine Tokens
 ~~~~~~~~~~~
@@ -181,7 +188,7 @@ Customise the permissions for your use case, but for a personal account full bac
 **User permissions**: Read access to followers, starring, and watching.
-**Repository permissions**: Read access to contents, issues, metadata, pull requests, and webhooks.
+**Repository permissions**: Read access to contents, discussions, issues, metadata, pull requests, and webhooks.
 GitHub Apps
@@ -262,9 +269,9 @@ LFS objects are fetched for all refs, not just the current checkout, ensuring a
 About Attachments
 -----------------
-When you use the ``--attachments`` option with ``--issues`` or ``--pulls``, the tool will download user-uploaded attachments (images, videos, documents, etc.) from issue and pull request descriptions and comments. In some circumstances attachments contain valuable data related to the topic, and without their backup important information or context might be lost inadvertently.
+When you use the ``--attachments`` option with ``--issues``, ``--pulls`` or ``--discussions``, the tool will download user-uploaded attachments (images, videos, documents, etc.) from issue, pull request and discussion descriptions and comments. In some circumstances attachments contain valuable data related to the topic, and without their backup important information or context might be lost inadvertently.
-Attachments are saved to ``issues/attachments/{issue_number}/`` and ``pulls/attachments/{pull_number}/`` directories, where ``{issue_number}`` is the GitHub issue number (e.g., issue #123 saves to ``issues/attachments/123/``). Each attachment directory contains:
+Attachments are saved to ``issues/attachments/{issue_number}/``, ``pulls/attachments/{pull_number}/`` and ``discussions/attachments/{discussion_number}/`` directories, where ``{issue_number}`` is the GitHub issue number (e.g., issue #123 saves to ``issues/attachments/123/``). Each attachment directory contains:
 - The downloaded attachment files (named by their GitHub identifier with appropriate file extensions)
 - If multiple attachments have the same filename, conflicts are resolved with numeric suffixes (e.g., ``report.pdf``, ``report_1.pdf``, ``report_2.pdf``)
@@ -284,6 +291,16 @@ The tool automatically extracts file extensions from HTTP headers to ensure file
 **Fine-grained token limitation:** Due to a GitHub platform limitation, fine-grained personal access tokens (``github_pat_...``) cannot download attachments from private repositories directly. This affects both ``/assets/`` (images) and ``/files/`` (documents) URLs. The tool implements a workaround for image attachments using GitHub's Markdown API, which converts URLs to temporary JWT-signed URLs that can be downloaded. However, this workaround only works for images - document attachments (PDFs, text files, etc.) will fail with 404 errors when using fine-grained tokens on private repos. For full attachment support on private repositories, use a classic token (``-t``) instead of a fine-grained token (``-f``). See `#477 <https://github.com/josegonzalez/python-github-backup/issues/477>`_ for details.
+About Discussions
+-----------------
+GitHub Discussions are backed up with GitHub's GraphQL API because the REST API does not expose discussions. Use ``--discussions`` to save each discussion as JSON under ``repositories/{repo}/discussions/{number}.json``. Discussion backups include the discussion body and metadata, category information, comments, and comment replies.
+``--discussions`` is included in ``--all``. Unlike most REST API-backed resources, discussions require authentication because GitHub's GraphQL API requires a token. Fine-grained personal access tokens and GitHub Apps need read access to the repository's Discussions permission.
+Incremental backups use a per-repository checkpoint at ``repositories/{repo}/discussions/last_update`` based on discussion ``updatedAt`` timestamps. This is separate from the repository-level ``last_update`` file so discussion activity is not missed if the repository's own update timestamp does not change. If you enable ``--discussions`` on an existing incremental backup, the first run performs a full discussions backup for each repository and creates the discussions checkpoint for future runs.
 About security advisories
 -------------------------
@@ -325,12 +342,24 @@ For finer control, avoid using ``--assets`` with starred repos, or use ``--skip-
 Alternatively, consider just storing links to starred repos in JSON format with ``--starred``.
+About pull request reviews
+--------------------------
+Use ``--pull-reviews`` with ``--pulls`` to include GitHub pull request review metadata under each pull request's ``review_data`` key. Reviews are separate from review comments: ``--pull-comments`` backs up inline review comments via ``comment_data`` and regular PR conversation comments via ``comment_regular_data``, while ``--pull-reviews`` backs up review state, submitted time, commit ID, and the top-level review body.
+``--pull-reviews`` is included in ``--all``. Incremental backups use a per-repository checkpoint at ``repositories/{repo}/pulls/reviews_last_update``. If ``--pull-reviews`` is enabled on an existing incremental backup, the first run performs a one-time backfill for pull request reviews so older PRs are not skipped by the existing pull request checkpoint. Existing ``comment_data``, ``comment_regular_data`` and ``commit_data`` fields are preserved when only review data is being added.
 Incremental Backup
 ------------------
-Using (``-i, --incremental``) will only request new data from the API **since the last run (successful or not)**. e.g. only request issues from the API since the last run.
+Using (``-i, --incremental``) will only request new data from the API **since the last successful resource backup**. e.g. only request issues from the API since the last issue backup for that repository.
+Incremental checkpoints for issue and pull request API backups are stored per resource in that repository's backup directory (for example ``repositories/{repo}/issues/last_update``, ``repositories/{repo}/pulls/last_update`` or ``starred/{owner}/{repo}/pulls/last_update``). Older versions stored a single global ``last_update`` file in the output directory root. During migration, the legacy global checkpoint is used as a fallback only for resource directories that already contain backup data but do not yet have their own checkpoint. New repositories or newly enabled resources with no existing data get a full backup instead of inheriting an unrelated global checkpoint.
+After all existing issue and pull request resource directories have per-resource checkpoints, the legacy global ``last_update`` file is removed automatically.
-This means any blocking errors on previous runs can cause a large amount of missing data in backups.
+This means any blocking errors on previous runs can cause missing data in backups for the affected repository resource.
 Using (``--incremental-by-files``) will request new data from the API **based on when the file was modified on filesystem**. e.g. if you modify the file yourself you may miss something.
@@ -343,7 +372,7 @@ Known blocking errors
 Some errors will block the backup run by exiting the script. e.g. receiving a 403 Forbidden error from the Github API.
-If the incremental argument is used, this will result in the next backup only requesting API data since the last blocked/failed run. Potentially causing unexpected large amounts of missing data.
+If the incremental argument is used, per-resource checkpoints are only advanced after that resource's backup work completes. A blocking error can still abort the overall run, but repositories and resources that were not processed will keep their previous checkpoints.
 It's therefore recommended to only use the incremental argument if the output/result is being actively monitored, or complimented with periodic full non-incremental runs, to avoid unexpected missing data in a regular backup runs.
@@ -416,14 +445,14 @@ Quietly and incrementally backup useful Github user data (public and private rep
     export FINE_ACCESS_TOKEN=SOME-GITHUB-TOKEN
     GH_USER=YOUR-GITHUB-USER
-    github-backup -f $FINE_ACCESS_TOKEN --prefer-ssh -o ~/github-backup/ -l error -P -i --all-starred --starred --watched --followers --following --issues --issue-comments --issue-events --pulls --pull-comments --pull-commits --labels --milestones --security-advisories --repositories --wikis --releases --assets --attachments --pull-details --gists --starred-gists $GH_USER
+    github-backup -f $FINE_ACCESS_TOKEN --prefer-ssh -o ~/github-backup/ -l error -P -i --all-starred --starred --watched --followers --following --issues --issue-comments --issue-events --pulls --pull-comments --pull-reviews --pull-commits --labels --milestones --security-advisories --discussions --repositories --wikis --releases --assets --attachments --pull-details --gists --starred-gists $GH_USER
 Debug an error/block or incomplete backup into a temporary directory. Omit "incremental" to fill a previous incomplete backup. ::
     export FINE_ACCESS_TOKEN=SOME-GITHUB-TOKEN
     GH_USER=YOUR-GITHUB-USER
-    github-backup -f $FINE_ACCESS_TOKEN -o /tmp/github-backup/ -l debug -P --all-starred --starred --watched --followers --following --issues --issue-comments --issue-events --pulls --pull-comments --pull-commits --labels --milestones --repositories --wikis --releases --assets --pull-details --gists --starred-gists $GH_USER
+    github-backup -f $FINE_ACCESS_TOKEN -o /tmp/github-backup/ -l debug -P --all-starred --starred --watched --followers --following --issues --issue-comments --issue-events --pulls --pull-comments --pull-reviews --pull-commits --labels --milestones --discussions --repositories --wikis --releases --assets --pull-details --gists --starred-gists $GH_USER
 Pipe a token from stdin to avoid storing it in environment variables or command history (Unix-like systems only)::
@@ -439,7 +468,7 @@ This tool creates backups only, there is no inbuilt restore command.
     cd /tmp/white-house/repositories/petitions/repository
     git push --mirror git@github.com:WhiteHouse/petitions.git
-**Issues, pull requests, comments, and other metadata** are saved as JSON files for archival purposes. The GitHub API does not support recreating this data faithfully, creating issues via the API has limitations:
+**Issues, pull requests, discussions, comments, and other metadata** are saved as JSON files for archival purposes. The GitHub API does not support recreating this data faithfully, creating issues via the API has limitations:
 - New issue/PR numbers are assigned (original numbers cannot be set)
 - Timestamps reflect creation time (original dates cannot be set)

github-backup 0.61.4__tar.gz → 0.62.0__tar.gz

github-backup 0.61.4tar.gz → 0.62.0tar.gz