From 3cda5a01fdf094ea33de7d3c02aa7cc60d553e9b Mon Sep 17 00:00:00 2001 From: Changaco Date: Fri, 10 Apr 2026 20:32:16 +0000 Subject: [PATCH 1/6] document that `--all` doesn't imply `--attachments` --- README.rst | 2 +- github_backup/github_backup.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 3a4be3b..ed037fd 100644 --- a/README.rst +++ b/README.rst @@ -325,7 +325,7 @@ Gotchas / Known-issues All is not everything --------------------- -The ``--all`` argument does not include: cloning private repos (``-P, --private``), cloning forks (``-F, --fork``), cloning starred repositories (``--all-starred``), ``--pull-details``, cloning LFS repositories (``--lfs``), cloning gists (``--gists``) or cloning starred gist repos (``--starred-gists``). See examples for more. +The ``--all`` argument does not include: downloading attachments from issue and pull request comments (``--attachments``), cloning private repos (``-P, --private``), cloning forks (``-F, --fork``), cloning starred repositories (``--all-starred``), ``--pull-details``, cloning LFS repositories (``--lfs``), cloning gists (``--gists``) or cloning starred gist repos (``--starred-gists``). See examples for more. Starred repository size ----------------------- diff --git a/github_backup/github_backup.py b/github_backup/github_backup.py index 8b96622..dc872c7 100644 --- a/github_backup/github_backup.py +++ b/github_backup/github_backup.py @@ -488,7 +488,7 @@ def parse_args(args=None): "--attachments", action="store_true", dest="include_attachments", - help="download user-attachments from issues, pull requests, and discussions", + help="download user-attachments from issues, pull requests, and discussions [*]", ) parser.add_argument( "--throttle-limit", From 543d76f24bc4eb808618e7a8b5ccbabea80fa700 Mon Sep 17 00:00:00 2001 From: Changaco Date: Fri, 10 Apr 2026 20:35:06 +0000 Subject: [PATCH 2/6] fix a typo in the README --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index ed037fd..e5f0f14 100644 --- a/README.rst +++ b/README.rst @@ -363,7 +363,7 @@ This means any blocking errors on previous runs can cause missing data in backup 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. -Still saver than the previous version. +Still safer than the previous version. Specifically, issues and pull requests are handled like this. From 9340aa3aaada4c2d41aa8f9c1b6164f9ee9ed082 Mon Sep 17 00:00:00 2001 From: Changaco Date: Fri, 10 Apr 2026 20:35:47 +0000 Subject: [PATCH 3/6] try to clarify what `--incremental` actually does --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index e5f0f14..1bd3ff6 100644 --- a/README.rst +++ b/README.rst @@ -365,7 +365,7 @@ Using (``--incremental-by-files``) will request new data from the API **based on Still safer than the previous version. -Specifically, issues and pull requests are handled like this. +Incremental backup only changes how issue and pull request data is fetched. Known blocking errors --------------------- From a2391a550e45ff4882f006696599fcd408317781 Mon Sep 17 00:00:00 2001 From: Changaco Date: Fri, 10 Apr 2026 20:37:05 +0000 Subject: [PATCH 4/6] remove pointless and unsafe `export`s in examples --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 1bd3ff6..33a89fb 100644 --- a/README.rst +++ b/README.rst @@ -429,12 +429,12 @@ Github Backup Examples Backup all repositories, including private ones using a classic token:: - export ACCESS_TOKEN=SOME-GITHUB-TOKEN + ACCESS_TOKEN=SOME-GITHUB-TOKEN github-backup WhiteHouse --token $ACCESS_TOKEN --organization --output-directory /tmp/white-house --repositories --private Use a fine-grained access token to backup a single organization repository with everything else (wiki, pull requests, comments, issues etc):: - export FINE_ACCESS_TOKEN=SOME-GITHUB-TOKEN + FINE_ACCESS_TOKEN=SOME-GITHUB-TOKEN ORGANIZATION=docker REPO=cli # e.g. git@github.com:docker/cli.git @@ -442,14 +442,14 @@ Use a fine-grained access token to backup a single organization repository with Quietly and incrementally backup useful Github user data (public and private repos with SSH) including; all issues, pulls, all public starred repos and gists (omitting "hooks", "releases" and therefore "assets" to prevent blocking). *Great for a cron job.* :: - export FINE_ACCESS_TOKEN=SOME-GITHUB-TOKEN + 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-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 + 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-reviews --pull-commits --labels --milestones --discussions --repositories --wikis --releases --assets --pull-details --gists --starred-gists $GH_USER From d30d9bfe6034b174ae3839f7aa13f4ad2eff4dc3 Mon Sep 17 00:00:00 2001 From: Changaco Date: Fri, 10 Apr 2026 20:38:31 +0000 Subject: [PATCH 5/6] eliminate trailing spaces --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 33a89fb..c4d0fd0 100644 --- a/README.rst +++ b/README.rst @@ -22,7 +22,7 @@ Using PIP via PyPI:: Using PIP via Github (more likely the latest version):: pip install git+https://github.com/josegonzalez/python-github-backup.git#egg=github-backup - + *Install note for python newcomers:* Python scripts are unlikely to be included in your ``$PATH`` by default, this means it cannot be run directly in terminal with ``$ github-backup ...``, you can either add python's install path to your environments ``$PATH`` or call the script directly e.g. using ``$ ~/.local/bin/github-backup``.* @@ -249,7 +249,7 @@ Note: When you run github-backup, you will be asked whether you want to allow " Github Rate-limit and Throttling -------------------------------- -"github-backup" will automatically throttle itself based on feedback from the Github API. +"github-backup" will automatically throttle itself based on feedback from the Github API. Their API is usually rate-limited to 5000 calls per hour. The API will ask github-backup to pause until a specific time when the limit is reset again (at the start of the next hour). This continues until the backup is complete. @@ -446,7 +446,7 @@ Quietly and incrementally backup useful Github user data (public and private rep 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-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. :: FINE_ACCESS_TOKEN=SOME-GITHUB-TOKEN From 8e76089565d7822bd94816433c2509daee40f26b Mon Sep 17 00:00:00 2001 From: Changaco Date: Sat, 25 Apr 2026 07:07:24 +0000 Subject: [PATCH 6/6] document that nothing is saved by default --- README.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.rst b/README.rst index c4d0fd0..c3d5d5d 100644 --- a/README.rst +++ b/README.rst @@ -327,6 +327,11 @@ All is not everything The ``--all`` argument does not include: downloading attachments from issue and pull request comments (``--attachments``), cloning private repos (``-P, --private``), cloning forks (``-F, --fork``), cloning starred repositories (``--all-starred``), ``--pull-details``, cloning LFS repositories (``--lfs``), cloning gists (``--gists``) or cloning starred gist repos (``--starred-gists``). See examples for more. +Saves nothing if no arguments are passed +---------------------------------------- + +At least one argument like ``--all`` or ``--repositories`` is needed for github-backup to actually save data. Without relevant arguments, github-backup fetches some data from GitHub but doesn't put any of it into files. + Starred repository size -----------------------