github-backup 0.57.0__py3-none-any.whl → 0.59.0__py3-none-any.whl

github_backup/__init__.py

@@ -1 +1 @@
-__version__ = "0.57.0"
+__version__ = "0.59.0"

github_backup/cli.py

@@ -43,7 +43,7 @@ def main():
     if args.private and not get_auth(args):
         logger.warning(
             "The --private flag has no effect without authentication. "
-            "Use -t/--token, -f/--token-fine, or -u/--username to authenticate."
+            "Use -t/--token or -f/--token-fine to authenticate."
         )
 
     if args.quiet:

github_backup/github_backup.py

@@ -7,11 +7,11 @@ import base64
 import calendar
 import codecs
 import errno
-import getpass
 import json
 import logging
 import os
 import platform
+import random
 import re
 import select
 import socket
@@ -19,10 +19,10 @@ import ssl
 import subprocess
 import sys
 import time
+from collections.abc import Generator
 from datetime import datetime
 from http.client import IncompleteRead
 from urllib.error import HTTPError, URLError
-from urllib.parse import quote as urlquote
 from urllib.parse import urlencode, urlparse
 from urllib.request import HTTPRedirectHandler, Request, build_opener, urlopen
 
@@ -74,6 +74,9 @@ else:
                 "  3. Debian/Ubuntu: apt-get install ca-certificates\n\n"
             )
 
+# Retry configuration
+MAX_RETRIES = 5
+
 
 def logging_subprocess(
     popenargs, stdout_log_level=logging.DEBUG, stderr_log_level=logging.ERROR, **kwargs
@@ -144,17 +147,6 @@ def mask_password(url, secret="*****"):
 def parse_args(args=None):
     parser = argparse.ArgumentParser(description="Backup a github account")
     parser.add_argument("user", metavar="USER", type=str, help="github username")
-    parser.add_argument(
-        "-u", "--username", dest="username", help="username for basic auth"
-    )
-    parser.add_argument(
-        "-p",
-        "--password",
-        dest="password",
-        help="password for basic auth. "
-        "If a username is given but not a password, the "
-        "password will be prompted for.",
-    )
     parser.add_argument(
         "-t",
         "--token",
@@ -219,6 +211,13 @@ def parse_args(args=None):
         dest="all_starred",
         help="include starred repositories in backup [*]",
     )
+    parser.add_argument(
+        "--starred-skip-size-over",
+        type=int,
+        metavar="MB",
+        dest="starred_skip_size_over",
+        help="skip starred repositories larger than this size in MB",
+    )
     parser.add_argument(
         "--watched",
         action="store_true",
@@ -528,16 +527,6 @@ def get_auth(args, encode=True, for_git_cli=False):
                 auth = args.token_classic
             else:
                 auth = "x-access-token:" + args.token_classic
-    elif args.username:
-        if not args.password:
-            args.password = getpass.getpass()
-        if encode:
-            password = args.password
-        else:
-            password = urlquote(args.password)
-        auth = args.username + ":" + password
-    elif args.password:
-        raise Exception("You must specify a username for basic auth")
 
     if not auth:
         return None
@@ -603,170 +592,178 @@ def get_github_repo_url(args, repository):
     return repo_url
 
 
-def retrieve_data_gen(args, template, query_args=None, single_request=False):
-    auth = get_auth(args, encode=not args.as_app)
-    query_args = get_query_args(query_args)
-    per_page = 100
-    next_url = None
+def calculate_retry_delay(attempt, headers):
+    """Calculate delay before next retry with exponential backoff."""
+    # Respect retry-after header if present
+    if retry_after := headers.get("retry-after"):
+        return int(retry_after)
 
-    while True:
-        if single_request:
-            request_per_page = None
-        else:
-            request_per_page = per_page
+    # Respect rate limit reset time
+    if int(headers.get("x-ratelimit-remaining", 1)) < 1:
+        reset_time = int(headers.get("x-ratelimit-reset", 0))
+        return max(10, reset_time - calendar.timegm(time.gmtime()))
 
-        request = _construct_request(
-            request_per_page,
-            query_args,
-            next_url or template,
-            auth,
-            as_app=args.as_app,
-            fine=True if args.token_fine is not None else False,
-        )  # noqa
-        r, errors = _get_response(request, auth, next_url or template)
+    # Exponential backoff with jitter for server errors (1s base, 120s max)
+    delay = min(1.0 * (2**attempt), 120.0)
+    return delay + random.uniform(0, delay * 0.1)
 
-        status_code = int(r.getcode())
 
-        # Handle DMCA takedown (HTTP 451) - raise exception to skip entire repository
-        if status_code == 451:
-            dmca_url = None
-            try:
-                response_data = json.loads(r.read().decode("utf-8"))
-                dmca_url = response_data.get("block", {}).get("html_url")
-            except Exception:
-                pass
-            raise RepositoryUnavailableError(
-                "Repository unavailable due to legal reasons (HTTP 451)",
-                dmca_url=dmca_url,
-            )
+def retrieve_data(args, template, query_args=None, paginated=True):
+    """
+    Fetch the data from GitHub API.
 
-        # Check if we got correct data
-        try:
-            response = json.loads(r.read().decode("utf-8"))
-        except IncompleteRead:
-            logger.warning("Incomplete read error detected")
-            read_error = True
-        except json.decoder.JSONDecodeError:
-            logger.warning("JSON decode error detected")
-            read_error = True
-        except TimeoutError:
-            logger.warning("Tiemout error detected")
-            read_error = True
-        else:
-            read_error = False
+    Handle both single requests and pagination with yield of individual dicts.
+    Handles throttling, retries, read errors, and DMCA takedowns.
+    """
+    query_args = query_args or {}
+    auth = get_auth(args, encode=not args.as_app)
+    per_page = 100
 
-        # be gentle with API request limit and throttle requests if remaining requests getting low
-        limit_remaining = int(r.headers.get("x-ratelimit-remaining", 0))
-        if args.throttle_limit and limit_remaining <= args.throttle_limit:
-            logger.info(
-                "API request limit hit: {} requests left, pausing further requests for {}s".format(
-                    limit_remaining, args.throttle_pause
+    def _extract_next_page_url(link_header):
+        for link in link_header.split(","):
+            if 'rel="next"' in link:
+                return link[link.find("<") + 1:link.find(">")]
+        return None
+
+    def fetch_all() -> Generator[dict, None, None]:
+        next_url = None
+
+        while True:
+            # FIRST: Fetch response
+
+            for attempt in range(MAX_RETRIES):
+                request = _construct_request(
+                    per_page=per_page if paginated else None,
+                    query_args=query_args,
+                    template=next_url or template,
+                    auth=auth,
+                    as_app=args.as_app,
+                    fine=args.token_fine is not None,
                 )
-            )
-            time.sleep(args.throttle_pause)
-
-        retries = 0
-        while retries < 3 and (status_code == 502 or read_error):
-            logger.warning("API request failed. Retrying in 5 seconds")
-            retries += 1
-            time.sleep(5)
-            request = _construct_request(
-                request_per_page,
-                query_args,
-                next_url or template,
-                auth,
-                as_app=args.as_app,
-                fine=True if args.token_fine is not None else False,
-            )  # noqa
-            r, errors = _get_response(request, auth, next_url or template)
-
-            status_code = int(r.getcode())
-            try:
-                response = json.loads(r.read().decode("utf-8"))
-                read_error = False
-            except IncompleteRead:
-                logger.warning("Incomplete read error detected")
-                read_error = True
-            except json.decoder.JSONDecodeError:
-                logger.warning("JSON decode error detected")
-                read_error = True
-            except TimeoutError:
-                logger.warning("Tiemout error detected")
-                read_error = True
-
-        if status_code != 200:
-            template = "API request returned HTTP {0}: {1}"
-            errors.append(template.format(status_code, r.reason))
-            raise Exception(", ".join(errors))
-
-        if read_error:
-            template = "API request problem reading response for {0}"
-            errors.append(template.format(request))
-            raise Exception(", ".join(errors))
-
-        if len(errors) == 0:
-            if type(response) is list:
-                for resp in response:
-                    yield resp
-                # Parse Link header for next page URL (cursor-based pagination)
-                link_header = r.headers.get("Link", "")
-                next_url = None
-                if link_header:
-                    # Parse Link header: <https://api.github.com/...?per_page=100&after=cursor>; rel="next"
-                    for link in link_header.split(","):
-                        if 'rel="next"' in link:
-                            next_url = link[link.find("<") + 1 : link.find(">")]
-                            break
-                if not next_url:
-                    break
-            elif type(response) is dict and single_request:
-                yield response
+                http_response = make_request_with_retry(request, auth)
+
+                match http_response.getcode():
+                    case 200:
+                        # Success - Parse JSON response
+                        try:
+                            response = json.loads(http_response.read().decode("utf-8"))
+                            break  # Exit retry loop and handle the data returned
+                        except (
+                            IncompleteRead,
+                            json.decoder.JSONDecodeError,
+                            TimeoutError,
+                        ) as e:
+                            logger.warning(f"{type(e).__name__} reading response")
+                            if attempt < MAX_RETRIES - 1:
+                                delay = calculate_retry_delay(attempt, {})
+                                logger.warning(
+                                    f"Retrying in {delay:.1f}s (attempt {attempt + 1}/{MAX_RETRIES})"
+                                )
+                                time.sleep(delay)
+                            continue  # Next retry attempt
+
+                    case 451:
+                        # DMCA takedown - extract URL if available, then raise
+                        dmca_url = None
+                        try:
+                            response_data = json.loads(
+                                http_response.read().decode("utf-8")
+                            )
+                            dmca_url = response_data.get("block", {}).get("html_url")
+                        except Exception:
+                            pass
+                        raise RepositoryUnavailableError(
+                            "Repository unavailable due to legal reasons (HTTP 451)",
+                            dmca_url=dmca_url,
+                        )
 
-        if len(errors) > 0:
-            raise Exception(", ".join(errors))
+                    case _:
+                        raise Exception(
+                            f"API request returned HTTP {http_response.getcode()}: {http_response.reason}"
+                        )
+            else:
+                logger.error(
+                    f"Failed to read response after {MAX_RETRIES} attempts for {next_url or template}"
+                )
+                raise Exception(
+                    f"Failed to read response after {MAX_RETRIES} attempts for {next_url or template}"
+                )
 
-        if single_request:
-            break
+            # SECOND: Process and paginate
 
+            # Pause before next request if rate limit is low
+            if (
+                remaining := int(http_response.headers.get("x-ratelimit-remaining", 0))
+            ) <= (args.throttle_limit or 0):
+                if args.throttle_limit:
+                    logger.info(
+                        f"Throttling: {remaining} requests left, pausing {args.throttle_pause}s"
+                    )
+                    time.sleep(args.throttle_pause)
 
-def retrieve_data(args, template, query_args=None, single_request=False):
-    return list(retrieve_data_gen(args, template, query_args, single_request))
+            # Yield results
+            if isinstance(response, list):
+                yield from response
+            elif isinstance(response, dict):
+                yield response
 
+            # Check for more pages
+            if not paginated or not (
+                next_url := _extract_next_page_url(
+                    http_response.headers.get("Link", "")
+                )
+            ):
+                break  # No more data
 
-def get_query_args(query_args=None):
-    if not query_args:
-        query_args = {}
-    return query_args
+    return list(fetch_all())
 
 
-def _get_response(request, auth, template):
-    retry_timeout = 3
-    errors = []
-    # We'll make requests in a loop so we can
-    # delay and retry in the case of rate-limiting
-    while True:
-        should_continue = False
+def make_request_with_retry(request, auth):
+    """Make HTTP request with automatic retry for transient errors."""
+
+    def is_retryable_status(status_code, headers):
+        # Server errors are always retryable
+        if status_code in (500, 502, 503, 504):
+            return True
+        # Rate limit (403/429) is retryable if limit exhausted
+        if status_code in (403, 429):
+            return int(headers.get("x-ratelimit-remaining", 1)) < 1
+        return False
+
+    for attempt in range(MAX_RETRIES):
         try:
-            r = urlopen(request, context=https_ctx)
+            return urlopen(request, context=https_ctx)
+
         except HTTPError as exc:
-            errors, should_continue = _request_http_error(exc, auth, errors)  # noqa
-            r = exc
-        except URLError as e:
-            logger.warning(e.reason)
-            should_continue, retry_timeout = _request_url_error(template, retry_timeout)
-            if not should_continue:
-                raise
-        except socket.error as e:
-            logger.warning(e.strerror)
-            should_continue, retry_timeout = _request_url_error(template, retry_timeout)
-            if not should_continue:
+            # HTTPError can be used as a response-like object
+            if not is_retryable_status(exc.code, exc.headers):
+                raise  # Non-retryable error
+
+            if attempt >= MAX_RETRIES - 1:
+                logger.error(f"HTTP {exc.code} failed after {MAX_RETRIES} attempts")
                 raise
 
-        if should_continue:
-            continue
+            delay = calculate_retry_delay(attempt, exc.headers)
+            logger.warning(
+                f"HTTP {exc.code}, retrying in {delay:.1f}s "
+                f"(attempt {attempt + 1}/{MAX_RETRIES})"
+            )
+            if auth is None and exc.code in (403, 429):
+                logger.info("Hint: Authenticate to raise your GitHub rate limit")
+            time.sleep(delay)
 
-        break
-    return r, errors
+        except (URLError, socket.error) as e:
+            if attempt >= MAX_RETRIES - 1:
+                logger.error(f"Connection error failed after {MAX_RETRIES} attempts: {e}")
+                raise
+            delay = calculate_retry_delay(attempt, {})
+            logger.warning(
+                f"Connection error: {e}, retrying in {delay:.1f}s "
+                f"(attempt {attempt + 1}/{MAX_RETRIES})"
+            )
+            time.sleep(delay)
+
+    raise Exception(f"Request failed after {MAX_RETRIES} attempts")  # pragma: no cover
 
 
 def _construct_request(per_page, query_args, template, auth, as_app=None, fine=False):
@@ -808,52 +805,6 @@ def _construct_request(per_page, query_args, template, auth, as_app=None, fine=F
     return request
 
 
-def _request_http_error(exc, auth, errors):
-    # HTTPError behaves like a Response so we can
-    # check the status code and headers to see exactly
-    # what failed.
-
-    should_continue = False
-    headers = exc.headers
-    limit_remaining = int(headers.get("x-ratelimit-remaining", 0))
-
-    if exc.code == 403 and limit_remaining < 1:
-        # The X-RateLimit-Reset header includes a
-        # timestamp telling us when the limit will reset
-        # so we can calculate how long to wait rather
-        # than inefficiently polling:
-        gm_now = calendar.timegm(time.gmtime())
-        reset = int(headers.get("x-ratelimit-reset", 0)) or gm_now
-        # We'll never sleep for less than 10 seconds:
-        delta = max(10, reset - gm_now)
-
-        limit = headers.get("x-ratelimit-limit")
-        logger.warning(
-            "Exceeded rate limit of {} requests; waiting {} seconds to reset".format(
-                limit, delta
-            )
-        )  # noqa
-
-        if auth is None:
-            logger.info("Hint: Authenticate to raise your GitHub rate limit")
-
-        time.sleep(delta)
-        should_continue = True
-    return errors, should_continue
-
-
-def _request_url_error(template, retry_timeout):
-    # In case of a connection timing out, we can retry a few time
-    # But we won't crash and not back-up the rest now
-    logger.info("'{}' timed out".format(template))
-    retry_timeout -= 1
-
-    if retry_timeout >= 0:
-        return True, retry_timeout
-
-    raise Exception("'{}' timed out to much, skipping!".format(template))
-
-
 class S3HTTPRedirectHandler(HTTPRedirectHandler):
     """
     A subclassed redirect handler for downloading Github assets from S3.
@@ -1503,7 +1454,7 @@ def download_attachments(
 
 def get_authenticated_user(args):
     template = "https://{0}/user".format(get_github_api_host(args))
-    data = retrieve_data(args, template, single_request=True)
+    data = retrieve_data(args, template, paginated=False)
     return data[0]
 
 
@@ -1517,7 +1468,7 @@ def check_git_lfs_install():
 
 def retrieve_repositories(args, authenticated_user):
     logger.info("Retrieving repositories")
-    single_request = False
+    paginated = True
     if args.user == authenticated_user["login"]:
         # we must use the /user/repos API to be able to access private repos
         template = "https://{0}/user/repos".format(get_github_api_host(args))
@@ -1540,16 +1491,16 @@ def retrieve_repositories(args, authenticated_user):
             repo_path = args.repository
         else:
             repo_path = "{0}/{1}".format(args.user, args.repository)
-        single_request = True
+        paginated = False
         template = "https://{0}/repos/{1}".format(get_github_api_host(args), repo_path)
 
-    repos = retrieve_data(args, template, single_request=single_request)
+    repos = retrieve_data(args, template, paginated=paginated)
 
     if args.all_starred:
         starred_template = "https://{0}/users/{1}/starred".format(
             get_github_api_host(args), args.user
         )
-        starred_repos = retrieve_data(args, starred_template, single_request=False)
+        starred_repos = retrieve_data(args, starred_template)
         # flag each repo as starred for downstream processing
         for item in starred_repos:
             item.update({"is_starred": True})
@@ -1559,7 +1510,7 @@ def retrieve_repositories(args, authenticated_user):
         gists_template = "https://{0}/users/{1}/gists".format(
             get_github_api_host(args), args.user
         )
-        gists = retrieve_data(args, gists_template, single_request=False)
+        gists = retrieve_data(args, gists_template)
         # flag each repo as a gist for downstream processing
         for item in gists:
             item.update({"is_gist": True})
@@ -1578,9 +1529,7 @@ def retrieve_repositories(args, authenticated_user):
             starred_gists_template = "https://{0}/gists/starred".format(
                 get_github_api_host(args)
             )
-            starred_gists = retrieve_data(
-                args, starred_gists_template, single_request=False
-            )
+            starred_gists = retrieve_data(args, starred_gists_template)
             # flag each repo as a starred gist for downstream processing
             for item in starred_gists:
                 item.update({"is_gist": True, "is_starred": True})
@@ -1628,6 +1577,25 @@ def filter_repositories(args, unfiltered_repositories):
         ]
     if args.skip_archived:
         repositories = [r for r in repositories if not r.get("archived")]
+    if args.starred_skip_size_over is not None:
+        if args.starred_skip_size_over <= 0:
+            logger.warning(
+                "--starred-skip-size-over must be greater than 0, ignoring"
+            )
+        else:
+            size_limit_kb = args.starred_skip_size_over * 1024
+            filtered = []
+            for r in repositories:
+                if r.get("is_starred") and r.get("size", 0) > size_limit_kb:
+                    size_mb = r.get("size", 0) / 1024
+                    logger.info(
+                        "Skipping starred repo {0} ({1:.0f} MB) due to --starred-skip-size-over {2}".format(
+                            r.get("full_name", r.get("name")), size_mb, args.starred_skip_size_over
+                        )
+                    )
+                else:
+                    filtered.append(r)
+            repositories = filtered
     if args.exclude:
         repositories = [
             r for r in repositories if "name" not in r or r["name"] not in args.exclude
@@ -1849,14 +1817,14 @@ def backup_pulls(args, repo_cwd, repository, repos_template):
         pull_states = ["open", "closed"]
         for pull_state in pull_states:
             query_args["state"] = pull_state
-            _pulls = retrieve_data_gen(args, _pulls_template, query_args=query_args)
+            _pulls = retrieve_data(args, _pulls_template, query_args=query_args)
             for pull in _pulls:
                 if args.since and pull["updated_at"] < args.since:
                     break
                 if not args.since or pull["updated_at"] >= args.since:
                     pulls[pull["number"]] = pull
     else:
-        _pulls = retrieve_data_gen(args, _pulls_template, query_args=query_args)
+        _pulls = retrieve_data(args, _pulls_template, query_args=query_args)
         for pull in _pulls:
             if args.since and pull["updated_at"] < args.since:
                 break
@@ -1864,7 +1832,7 @@ def backup_pulls(args, repo_cwd, repository, repos_template):
                 pulls[pull["number"]] = retrieve_data(
                     args,
                     _pulls_template + "/{}".format(pull["number"]),
-                    single_request=True,
+                    paginated=False,
                 )[0]
 
     logger.info("Saving {0} pull requests to disk".format(len(list(pulls.keys()))))

{github_backup-0.57.0.dist-info → github_backup-0.59.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-backup
-Version: 0.57.0
+Version: 0.59.0
 Summary: backup a github user or organization
 Home-page: http://github.com/josegonzalez/python-github-backup
 Author: Jose Diaz-Gonzalez
@@ -66,23 +66,26 @@ Show the CLI help output::
 
 CLI Help output::
 
-    github-backup [-h] [-u USERNAME] [-p PASSWORD] [-t TOKEN_CLASSIC]
-                  [-f TOKEN_FINE] [--as-app] [-o OUTPUT_DIRECTORY]
-                  [-l LOG_LEVEL] [-i] [--starred] [--all-starred]
-                  [--watched] [--followers] [--following] [--all] [--issues]
-                  [--issue-comments] [--issue-events] [--pulls]
+    github-backup [-h] [-t TOKEN_CLASSIC] [-f TOKEN_FINE] [-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]
                   [--labels] [--hooks] [--milestones] [--repositories]
-                  [--bare] [--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]
+                  [--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]
                   [--keychain-account OSX_KEYCHAIN_ITEM_ACCOUNT]
                   [--releases] [--latest-releases NUMBER_OF_LATEST_RELEASES]
-                  [--skip-prerelease] [--assets] [--skip-assets-on [REPO ...]]
-                  [--attachments] [--exclude [REPOSITORY [REPOSITORY ...]]
-                  [--throttle-limit THROTTLE_LIMIT] [--throttle-pause THROTTLE_PAUSE]
+                  [--skip-prerelease] [--assets]
+                  [--skip-assets-on [SKIP_ASSETS_ON ...]] [--attachments]
+                  [--throttle-limit THROTTLE_LIMIT]
+                  [--throttle-pause THROTTLE_PAUSE]
+                  [--exclude [EXCLUDE ...]]
                   USER
 
     Backup a github account
@@ -90,29 +93,29 @@ CLI Help output::
     positional arguments:
       USER                  github username
 
-    optional arguments:
+    options:
       -h, --help            show this help message and exit
-      -u USERNAME, --username USERNAME
-                            username for basic auth
-      -p PASSWORD, --password PASSWORD
-                            password for basic auth. If a username is given but
-                            not a password, the password will be prompted for.
-      -f TOKEN_FINE, --token-fine TOKEN_FINE
-                            fine-grained personal access token or path to token
-                            (file://...)
-      -t TOKEN_CLASSIC, --token TOKEN_CLASSIC
+      -t, --token TOKEN_CLASSIC
                             personal access, OAuth, or JSON Web token, or path to
                             token (file://...)
+      -f, --token-fine TOKEN_FINE
+                            fine-grained personal access token (github_pat_....),
+                            or path to token (file://...)
+      -q, --quiet           supress log messages less severe than warning, e.g.
+                            info
       --as-app              authenticate as github app instead of as a user.
-      -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
+      -o, --output-directory OUTPUT_DIRECTORY
                             directory at which to backup the repositories
-      -l LOG_LEVEL, --log-level LOG_LEVEL
+      -l, --log-level LOG_LEVEL
                             log level to use (default: info, possible levels:
                             debug, info, warning, error, critical)
       -i, --incremental     incremental backup
-      --incremental-by-files incremental backup using modified time of files
+      --incremental-by-files
+                            incremental backup based on modification date of files
       --starred             include JSON output of starred repositories in backup
       --all-starred         include starred repositories in backup [*]
+      --starred-skip-size-over MB
+                            skip starred repositories larger than this size in MB
       --watched             include JSON output of watched repositories in backup
       --followers           include JSON output of followers in backup
       --following           include JSON output of following users in backup
@@ -130,20 +133,22 @@ CLI Help output::
       --milestones          include milestones in backup
       --repositories        include repository clone in backup
       --bare                clone bare repositories
+      --no-prune            disable prune option for git fetch
       --lfs                 clone LFS repositories (requires Git LFS to be
                             installed, https://git-lfs.github.com) [*]
       --wikis               include wiki clone in backup
       --gists               include gists in backup [*]
       --starred-gists       include starred gists in backup [*]
+      --skip-archived       skip project if it is archived
       --skip-existing       skip project if a backup directory exists
-      -L [LANGUAGES [LANGUAGES ...]], --languages [LANGUAGES [LANGUAGES ...]]
+      -L, --languages [LANGUAGES ...]
                             only allow these languages
-      -N NAME_REGEX, --name-regex NAME_REGEX
+      -N, --name-regex NAME_REGEX
                             python regex to match names against
-      -H GITHUB_HOST, --github-host GITHUB_HOST
+      -H, --github-host GITHUB_HOST
                             GitHub Enterprise hostname
       -O, --organization    whether or not this is an organization user
-      -R REPOSITORY, --repository REPOSITORY
+      -R, --repository REPOSITORY
                             name of repository to limit backup to
       -P, --private         include private repositories [*]
       -F, --fork            include forked repositories [*]
@@ -158,19 +163,16 @@ CLI Help output::
       --releases            include release information, not including assets or
                             binaries
       --latest-releases NUMBER_OF_LATEST_RELEASES
-                            include certain number of the latest releases;
-                            only applies if including releases
-      --skip-prerelease     skip prerelease and draft versions; only applies if including releases
+                            include certain number of the latest releases; only
+                            applies if including releases
+      --skip-prerelease     skip prerelease and draft versions; only applies if
+                            including releases
       --assets              include assets alongside release information; only
                             applies if including releases
-      --skip-assets-on [REPO ...]
-                            skip asset downloads for these repositories (e.g.
-                            --skip-assets-on repo1 owner/repo2)
-      --attachments         download user-attachments from issues and pull requests
-                            to issues/attachments/{issue_number}/ and
-                            pulls/attachments/{pull_number}/ directories
-      --exclude [REPOSITORY [REPOSITORY ...]]
-                            names of repositories to exclude from backup.
+      --skip-assets-on [SKIP_ASSETS_ON ...]
+                            skip asset downloads for these repositories
+      --attachments         download user-attachments from issues and pull
+                            requests
       --throttle-limit THROTTLE_LIMIT
                             start throttling of GitHub API requests after this
                             amount of API requests remain
@@ -178,6 +180,8 @@ CLI Help output::
                             wait this amount of seconds when API request
                             throttling is active (default: 30.0, requires
                             --throttle-limit to be set)
+      --exclude [EXCLUDE ...]
+                            names of repositories to exclude
 
 
 Usage Details
@@ -186,13 +190,13 @@ Usage Details
 Authentication
 --------------
 
-**Password-based authentication** will fail if you have two-factor authentication enabled, and will `be deprecated <https://github.blog/2023-03-09-raising-the-bar-for-software-security-github-2fa-begins-march-13/>`_ by 2023 EOY.
+GitHub requires token-based authentication for API access. Password authentication was `removed in November 2020 <https://developer.github.com/changes/2020-02-14-deprecating-password-auth/>`_.
 
-``--username`` is used for basic password authentication and separate from the positional argument ``USER``, which specifies the user account you wish to back up.
+The positional argument ``USER`` specifies the user or organization account you wish to back up.
 
-**Classic tokens** 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.
+**Fine-grained tokens** (``-f TOKEN_FINE``) are recommended for most use cases, especially long-running backups (e.g. cron jobs), as they provide precise permission control.
 
-If you need authentication for long-running backups (e.g. for a cron job) it is recommended to use **fine-grained personal access token** ``-f TOKEN_FINE``.
+**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.
 
 
 Fine Tokens
@@ -320,10 +324,20 @@ 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.
 
-Cloning all starred size
-------------------------
+Starred repository size
+-----------------------
+
+Using the ``--all-starred`` argument to clone all starred repositories may use a large amount of storage space.
+
+To see your starred repositories sorted by size (requires `GitHub CLI <https://cli.github.com>`_)::
+
+    gh api user/starred --paginate --jq 'sort_by(-.size)[]|"\(.full_name) \(.size/1024|round)MB"'
+
+To limit which starred repositories are cloned, use ``--starred-skip-size-over SIZE`` where SIZE is in MB. For example, ``--starred-skip-size-over 500`` will skip any starred repository where the git repository size (code and history) exceeds 500 MB. Note that this size limit only applies to the repository itself, not issues, release assets or other metadata. This filter only affects starred repositories; your own repositories are always included regardless of size.
+
+For finer control, avoid using ``--assets`` with starred repos, or use ``--skip-assets-on`` for specific repositories with large release binaries.
 
-Using the ``--all-starred`` argument to clone all starred repositories may use a large amount of storage space, especially if ``--all`` or more arguments are used. e.g. commonly starred repos can have tens of thousands of issues, many large assets and the repo itself etc. Consider just storing links to starred repos in JSON format with ``--starred``.
+Alternatively, consider just storing links to starred repos in JSON format with ``--starred``.
 
 Incremental Backup
 ------------------

github_backup-0.59.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+github_backup/__init__.py,sha256=HMyZ2jNndR4_RS4EcSAHrVoKBifJVKSLuqmMuKnl_JI,23
+github_backup/__main__.py,sha256=3yorCiC63maaxbjdtaeAs-G-yAAxKSO3mprhGfa1Fho,271
+github_backup/cli.py,sha256=ifnOne5AaEI7laofgIq3geURJtvbA-bzxSQgLcmZgd0,2345
+github_backup/github_backup.py,sha256=VkUaqxAMT3ooQ4xGp54xpUtAJL4h4zZ8b_-EtrFi2T4,81615
+github_backup-0.59.0.dist-info/licenses/LICENSE.txt,sha256=ML-pLyn1qtAKo_DHMcQ8-p7k3f8cp-IR-mf5B49R2rk,1085
+github_backup-0.59.0.dist-info/METADATA,sha256=_IyD8iBRAXp-Kkz1Ru0pkwjzVNDECjB6jKN6IR3n-Sk,26421
+github_backup-0.59.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+github_backup-0.59.0.dist-info/entry_points.txt,sha256=cLPKK7MqC77QVb6HnT2mnyL_f-ciavJG_Y9vVHlCF68,57
+github_backup-0.59.0.dist-info/top_level.txt,sha256=Za6fKRAlxZ0b3ZBH_osPqklLe14LetdNAkvAQANT2AA,14
+github_backup-0.59.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+github_backup-0.59.0.dist-info/RECORD,,

github_backup-0.57.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-github_backup/__init__.py,sha256=jmnoPljZ40w5Zc7DEZpxkJSfC9yHbRjV50qzvnfEbdI,23
-github_backup/__main__.py,sha256=3yorCiC63maaxbjdtaeAs-G-yAAxKSO3mprhGfa1Fho,271
-github_backup/cli.py,sha256=zMUU0pTnh9KPqv8K--KNpUNf-yaA1qWeI6AdC1KVrn8,2361
-github_backup/github_backup.py,sha256=_P0WVPpZpyzs3PPkwtmIWDu2mkmeGXd2EePymeEtOV0,81890
-github_backup-0.57.0.dist-info/licenses/LICENSE.txt,sha256=ML-pLyn1qtAKo_DHMcQ8-p7k3f8cp-IR-mf5B49R2rk,1085
-github_backup-0.57.0.dist-info/METADATA,sha256=4Jni1TDR6oVFdIKCzjy6hacTh1TQrigaAeXVyidL-As,25921
-github_backup-0.57.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-github_backup-0.57.0.dist-info/entry_points.txt,sha256=cLPKK7MqC77QVb6HnT2mnyL_f-ciavJG_Y9vVHlCF68,57
-github_backup-0.57.0.dist-info/top_level.txt,sha256=Za6fKRAlxZ0b3ZBH_osPqklLe14LetdNAkvAQANT2AA,14
-github_backup-0.57.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-github_backup-0.57.0.dist-info/RECORD,,