github-backup 0.58.0__tar.gz → 0.59.0__tar.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.
- {github_backup-0.58.0 → github_backup-0.59.0}/CHANGES.rst +18 -1
- {github_backup-0.58.0/github_backup.egg-info → github_backup-0.59.0}/PKG-INFO +62 -48
- {github_backup-0.58.0 → github_backup-0.59.0}/README +61 -47
- {github_backup-0.58.0 → github_backup-0.59.0}/README.rst +61 -47
- github_backup-0.59.0/github_backup/__init__.py +1 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/github_backup/cli.py +1 -1
- {github_backup-0.58.0 → github_backup-0.59.0}/github_backup/github_backup.py +26 -23
- {github_backup-0.58.0 → github_backup-0.59.0/github_backup.egg-info}/PKG-INFO +62 -48
- {github_backup-0.58.0 → github_backup-0.59.0}/github_backup.egg-info/SOURCES.txt +2 -1
- {github_backup-0.58.0 → github_backup-0.59.0}/tests/test_all_starred.py +0 -2
- {github_backup-0.58.0 → github_backup-0.59.0}/tests/test_attachments.py +0 -2
- {github_backup-0.58.0 → github_backup-0.59.0}/tests/test_case_sensitivity.py +6 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/tests/test_http_451.py +0 -6
- {github_backup-0.58.0 → github_backup-0.59.0}/tests/test_pagination.py +0 -2
- {github_backup-0.58.0 → github_backup-0.59.0}/tests/test_retrieve_data.py +0 -6
- {github_backup-0.58.0 → github_backup-0.59.0}/tests/test_skip_assets_on.py +0 -2
- github_backup-0.59.0/tests/test_starred_skip_size_over.py +224 -0
- github_backup-0.58.0/github_backup/__init__.py +0 -1
- {github_backup-0.58.0 → github_backup-0.59.0}/LICENSE.txt +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/MANIFEST.in +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/github_backup/__main__.py +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/github_backup.egg-info/dependency_links.txt +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/github_backup.egg-info/entry_points.txt +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/github_backup.egg-info/top_level.txt +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/github_backup.egg-info/zip-safe +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/release-requirements.txt +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/requirements.txt +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/setup.cfg +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/setup.py +0 -0
- {github_backup-0.58.0 → github_backup-0.59.0}/tests/test_json_dump_if_changed.py +0 -0
|
@@ -1,9 +1,26 @@
|
|
|
1
1
|
Changelog
|
|
2
2
|
=========
|
|
3
3
|
|
|
4
|
-
0.
|
|
4
|
+
0.59.0 (2025-12-21)
|
|
5
5
|
-------------------
|
|
6
6
|
------------------------
|
|
7
|
+
- Add --starred-skip-size-over flag to limit starred repo size (#108)
|
|
8
|
+
[Rodos]
|
|
9
|
+
|
|
10
|
+
Allow users to skip starred repositories exceeding a size threshold
|
|
11
|
+
when using --all-starred. Size is specified in MB and checked against
|
|
12
|
+
the GitHub API's repository size field.
|
|
13
|
+
|
|
14
|
+
- Only affects starred repos; user's own repos always included
|
|
15
|
+
- Logs each skipped repo with name and size
|
|
16
|
+
|
|
17
|
+
Closes #108
|
|
18
|
+
- Chore: remove deprecated -u/-p password authentication options.
|
|
19
|
+
[Rodos]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
0.58.0 (2025-12-16)
|
|
23
|
+
-------------------
|
|
7
24
|
- Fix retry logic for HTTP 5xx errors and network failures. [Rodos]
|
|
8
25
|
|
|
9
26
|
Refactors error handling to retry all 5xx errors (not just 502), network errors (URLError, socket.error, IncompleteRead), and JSON parse errors with exponential backoff and jitter. Respects retry-after and rate limit headers per GitHub API requirements. Consolidates retry logic into make_request_with_retry() wrapper and adds clear logging for retry attempts and failures. Removes dead code from 2016 (errors list, _request_http_error, _request_url_error) that was intentionally disabled in commit 1e5a9048 to fix #29.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: github-backup
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.59.0
|
|
4
4
|
Summary: backup a github user or organization
|
|
5
5
|
Home-page: http://github.com/josegonzalez/python-github-backup
|
|
6
6
|
Author: Jose Diaz-Gonzalez
|
|
@@ -66,23 +66,26 @@ Show the CLI help output::
|
|
|
66
66
|
|
|
67
67
|
CLI Help output::
|
|
68
68
|
|
|
69
|
-
github-backup [-h] [-
|
|
70
|
-
[-
|
|
71
|
-
[-
|
|
72
|
-
[--
|
|
73
|
-
[--
|
|
69
|
+
github-backup [-h] [-t TOKEN_CLASSIC] [-f TOKEN_FINE] [-q] [--as-app]
|
|
70
|
+
[-o OUTPUT_DIRECTORY] [-l LOG_LEVEL] [-i]
|
|
71
|
+
[--incremental-by-files]
|
|
72
|
+
[--starred] [--all-starred] [--starred-skip-size-over MB]
|
|
73
|
+
[--watched] [--followers] [--following] [--all]
|
|
74
|
+
[--issues] [--issue-comments] [--issue-events] [--pulls]
|
|
74
75
|
[--pull-comments] [--pull-commits] [--pull-details]
|
|
75
76
|
[--labels] [--hooks] [--milestones] [--repositories]
|
|
76
|
-
[--bare] [--
|
|
77
|
-
[--
|
|
78
|
-
[-
|
|
79
|
-
[-P] [-F] [--prefer-ssh] [-v]
|
|
77
|
+
[--bare] [--no-prune] [--lfs] [--wikis] [--gists]
|
|
78
|
+
[--starred-gists] [--skip-archived] [--skip-existing]
|
|
79
|
+
[-L [LANGUAGES ...]] [-N NAME_REGEX] [-H GITHUB_HOST]
|
|
80
|
+
[-O] [-R REPOSITORY] [-P] [-F] [--prefer-ssh] [-v]
|
|
80
81
|
[--keychain-name OSX_KEYCHAIN_ITEM_NAME]
|
|
81
82
|
[--keychain-account OSX_KEYCHAIN_ITEM_ACCOUNT]
|
|
82
83
|
[--releases] [--latest-releases NUMBER_OF_LATEST_RELEASES]
|
|
83
|
-
[--skip-prerelease] [--assets]
|
|
84
|
-
[--
|
|
85
|
-
[--throttle-limit THROTTLE_LIMIT]
|
|
84
|
+
[--skip-prerelease] [--assets]
|
|
85
|
+
[--skip-assets-on [SKIP_ASSETS_ON ...]] [--attachments]
|
|
86
|
+
[--throttle-limit THROTTLE_LIMIT]
|
|
87
|
+
[--throttle-pause THROTTLE_PAUSE]
|
|
88
|
+
[--exclude [EXCLUDE ...]]
|
|
86
89
|
USER
|
|
87
90
|
|
|
88
91
|
Backup a github account
|
|
@@ -90,29 +93,29 @@ CLI Help output::
|
|
|
90
93
|
positional arguments:
|
|
91
94
|
USER github username
|
|
92
95
|
|
|
93
|
-
|
|
96
|
+
options:
|
|
94
97
|
-h, --help show this help message and exit
|
|
95
|
-
-
|
|
96
|
-
username for basic auth
|
|
97
|
-
-p PASSWORD, --password PASSWORD
|
|
98
|
-
password for basic auth. If a username is given but
|
|
99
|
-
not a password, the password will be prompted for.
|
|
100
|
-
-f TOKEN_FINE, --token-fine TOKEN_FINE
|
|
101
|
-
fine-grained personal access token or path to token
|
|
102
|
-
(file://...)
|
|
103
|
-
-t TOKEN_CLASSIC, --token TOKEN_CLASSIC
|
|
98
|
+
-t, --token TOKEN_CLASSIC
|
|
104
99
|
personal access, OAuth, or JSON Web token, or path to
|
|
105
100
|
token (file://...)
|
|
101
|
+
-f, --token-fine TOKEN_FINE
|
|
102
|
+
fine-grained personal access token (github_pat_....),
|
|
103
|
+
or path to token (file://...)
|
|
104
|
+
-q, --quiet supress log messages less severe than warning, e.g.
|
|
105
|
+
info
|
|
106
106
|
--as-app authenticate as github app instead of as a user.
|
|
107
|
-
-o
|
|
107
|
+
-o, --output-directory OUTPUT_DIRECTORY
|
|
108
108
|
directory at which to backup the repositories
|
|
109
|
-
-l
|
|
109
|
+
-l, --log-level LOG_LEVEL
|
|
110
110
|
log level to use (default: info, possible levels:
|
|
111
111
|
debug, info, warning, error, critical)
|
|
112
112
|
-i, --incremental incremental backup
|
|
113
|
-
--incremental-by-files
|
|
113
|
+
--incremental-by-files
|
|
114
|
+
incremental backup based on modification date of files
|
|
114
115
|
--starred include JSON output of starred repositories in backup
|
|
115
116
|
--all-starred include starred repositories in backup [*]
|
|
117
|
+
--starred-skip-size-over MB
|
|
118
|
+
skip starred repositories larger than this size in MB
|
|
116
119
|
--watched include JSON output of watched repositories in backup
|
|
117
120
|
--followers include JSON output of followers in backup
|
|
118
121
|
--following include JSON output of following users in backup
|
|
@@ -130,20 +133,22 @@ CLI Help output::
|
|
|
130
133
|
--milestones include milestones in backup
|
|
131
134
|
--repositories include repository clone in backup
|
|
132
135
|
--bare clone bare repositories
|
|
136
|
+
--no-prune disable prune option for git fetch
|
|
133
137
|
--lfs clone LFS repositories (requires Git LFS to be
|
|
134
138
|
installed, https://git-lfs.github.com) [*]
|
|
135
139
|
--wikis include wiki clone in backup
|
|
136
140
|
--gists include gists in backup [*]
|
|
137
141
|
--starred-gists include starred gists in backup [*]
|
|
142
|
+
--skip-archived skip project if it is archived
|
|
138
143
|
--skip-existing skip project if a backup directory exists
|
|
139
|
-
-L
|
|
144
|
+
-L, --languages [LANGUAGES ...]
|
|
140
145
|
only allow these languages
|
|
141
|
-
-N
|
|
146
|
+
-N, --name-regex NAME_REGEX
|
|
142
147
|
python regex to match names against
|
|
143
|
-
-H
|
|
148
|
+
-H, --github-host GITHUB_HOST
|
|
144
149
|
GitHub Enterprise hostname
|
|
145
150
|
-O, --organization whether or not this is an organization user
|
|
146
|
-
-R
|
|
151
|
+
-R, --repository REPOSITORY
|
|
147
152
|
name of repository to limit backup to
|
|
148
153
|
-P, --private include private repositories [*]
|
|
149
154
|
-F, --fork include forked repositories [*]
|
|
@@ -158,19 +163,16 @@ CLI Help output::
|
|
|
158
163
|
--releases include release information, not including assets or
|
|
159
164
|
binaries
|
|
160
165
|
--latest-releases NUMBER_OF_LATEST_RELEASES
|
|
161
|
-
include certain number of the latest releases;
|
|
162
|
-
|
|
163
|
-
--skip-prerelease skip prerelease and draft versions; only applies if
|
|
166
|
+
include certain number of the latest releases; only
|
|
167
|
+
applies if including releases
|
|
168
|
+
--skip-prerelease skip prerelease and draft versions; only applies if
|
|
169
|
+
including releases
|
|
164
170
|
--assets include assets alongside release information; only
|
|
165
171
|
applies if including releases
|
|
166
|
-
--skip-assets-on [
|
|
167
|
-
skip asset downloads for these repositories
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
to issues/attachments/{issue_number}/ and
|
|
171
|
-
pulls/attachments/{pull_number}/ directories
|
|
172
|
-
--exclude [REPOSITORY [REPOSITORY ...]]
|
|
173
|
-
names of repositories to exclude from backup.
|
|
172
|
+
--skip-assets-on [SKIP_ASSETS_ON ...]
|
|
173
|
+
skip asset downloads for these repositories
|
|
174
|
+
--attachments download user-attachments from issues and pull
|
|
175
|
+
requests
|
|
174
176
|
--throttle-limit THROTTLE_LIMIT
|
|
175
177
|
start throttling of GitHub API requests after this
|
|
176
178
|
amount of API requests remain
|
|
@@ -178,6 +180,8 @@ CLI Help output::
|
|
|
178
180
|
wait this amount of seconds when API request
|
|
179
181
|
throttling is active (default: 30.0, requires
|
|
180
182
|
--throttle-limit to be set)
|
|
183
|
+
--exclude [EXCLUDE ...]
|
|
184
|
+
names of repositories to exclude
|
|
181
185
|
|
|
182
186
|
|
|
183
187
|
Usage Details
|
|
@@ -186,13 +190,13 @@ Usage Details
|
|
|
186
190
|
Authentication
|
|
187
191
|
--------------
|
|
188
192
|
|
|
189
|
-
|
|
193
|
+
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/>`_.
|
|
190
194
|
|
|
191
|
-
|
|
195
|
+
The positional argument ``USER`` specifies the user or organization account you wish to back up.
|
|
192
196
|
|
|
193
|
-
**
|
|
197
|
+
**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.
|
|
194
198
|
|
|
195
|
-
|
|
199
|
+
**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.
|
|
196
200
|
|
|
197
201
|
|
|
198
202
|
Fine Tokens
|
|
@@ -320,10 +324,20 @@ All is not everything
|
|
|
320
324
|
|
|
321
325
|
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.
|
|
322
326
|
|
|
323
|
-
|
|
324
|
-
|
|
327
|
+
Starred repository size
|
|
328
|
+
-----------------------
|
|
329
|
+
|
|
330
|
+
Using the ``--all-starred`` argument to clone all starred repositories may use a large amount of storage space.
|
|
331
|
+
|
|
332
|
+
To see your starred repositories sorted by size (requires `GitHub CLI <https://cli.github.com>`_)::
|
|
333
|
+
|
|
334
|
+
gh api user/starred --paginate --jq 'sort_by(-.size)[]|"\(.full_name) \(.size/1024|round)MB"'
|
|
335
|
+
|
|
336
|
+
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.
|
|
337
|
+
|
|
338
|
+
For finer control, avoid using ``--assets`` with starred repos, or use ``--skip-assets-on`` for specific repositories with large release binaries.
|
|
325
339
|
|
|
326
|
-
|
|
340
|
+
Alternatively, consider just storing links to starred repos in JSON format with ``--starred``.
|
|
327
341
|
|
|
328
342
|
Incremental Backup
|
|
329
343
|
------------------
|
|
@@ -36,23 +36,26 @@ Show the CLI help output::
|
|
|
36
36
|
|
|
37
37
|
CLI Help output::
|
|
38
38
|
|
|
39
|
-
github-backup [-h] [-
|
|
40
|
-
[-
|
|
41
|
-
[-
|
|
42
|
-
[--
|
|
43
|
-
[--
|
|
39
|
+
github-backup [-h] [-t TOKEN_CLASSIC] [-f TOKEN_FINE] [-q] [--as-app]
|
|
40
|
+
[-o OUTPUT_DIRECTORY] [-l LOG_LEVEL] [-i]
|
|
41
|
+
[--incremental-by-files]
|
|
42
|
+
[--starred] [--all-starred] [--starred-skip-size-over MB]
|
|
43
|
+
[--watched] [--followers] [--following] [--all]
|
|
44
|
+
[--issues] [--issue-comments] [--issue-events] [--pulls]
|
|
44
45
|
[--pull-comments] [--pull-commits] [--pull-details]
|
|
45
46
|
[--labels] [--hooks] [--milestones] [--repositories]
|
|
46
|
-
[--bare] [--
|
|
47
|
-
[--
|
|
48
|
-
[-
|
|
49
|
-
[-P] [-F] [--prefer-ssh] [-v]
|
|
47
|
+
[--bare] [--no-prune] [--lfs] [--wikis] [--gists]
|
|
48
|
+
[--starred-gists] [--skip-archived] [--skip-existing]
|
|
49
|
+
[-L [LANGUAGES ...]] [-N NAME_REGEX] [-H GITHUB_HOST]
|
|
50
|
+
[-O] [-R REPOSITORY] [-P] [-F] [--prefer-ssh] [-v]
|
|
50
51
|
[--keychain-name OSX_KEYCHAIN_ITEM_NAME]
|
|
51
52
|
[--keychain-account OSX_KEYCHAIN_ITEM_ACCOUNT]
|
|
52
53
|
[--releases] [--latest-releases NUMBER_OF_LATEST_RELEASES]
|
|
53
|
-
[--skip-prerelease] [--assets]
|
|
54
|
-
[--
|
|
55
|
-
[--throttle-limit THROTTLE_LIMIT]
|
|
54
|
+
[--skip-prerelease] [--assets]
|
|
55
|
+
[--skip-assets-on [SKIP_ASSETS_ON ...]] [--attachments]
|
|
56
|
+
[--throttle-limit THROTTLE_LIMIT]
|
|
57
|
+
[--throttle-pause THROTTLE_PAUSE]
|
|
58
|
+
[--exclude [EXCLUDE ...]]
|
|
56
59
|
USER
|
|
57
60
|
|
|
58
61
|
Backup a github account
|
|
@@ -60,29 +63,29 @@ CLI Help output::
|
|
|
60
63
|
positional arguments:
|
|
61
64
|
USER github username
|
|
62
65
|
|
|
63
|
-
|
|
66
|
+
options:
|
|
64
67
|
-h, --help show this help message and exit
|
|
65
|
-
-
|
|
66
|
-
username for basic auth
|
|
67
|
-
-p PASSWORD, --password PASSWORD
|
|
68
|
-
password for basic auth. If a username is given but
|
|
69
|
-
not a password, the password will be prompted for.
|
|
70
|
-
-f TOKEN_FINE, --token-fine TOKEN_FINE
|
|
71
|
-
fine-grained personal access token or path to token
|
|
72
|
-
(file://...)
|
|
73
|
-
-t TOKEN_CLASSIC, --token TOKEN_CLASSIC
|
|
68
|
+
-t, --token TOKEN_CLASSIC
|
|
74
69
|
personal access, OAuth, or JSON Web token, or path to
|
|
75
70
|
token (file://...)
|
|
71
|
+
-f, --token-fine TOKEN_FINE
|
|
72
|
+
fine-grained personal access token (github_pat_....),
|
|
73
|
+
or path to token (file://...)
|
|
74
|
+
-q, --quiet supress log messages less severe than warning, e.g.
|
|
75
|
+
info
|
|
76
76
|
--as-app authenticate as github app instead of as a user.
|
|
77
|
-
-o
|
|
77
|
+
-o, --output-directory OUTPUT_DIRECTORY
|
|
78
78
|
directory at which to backup the repositories
|
|
79
|
-
-l
|
|
79
|
+
-l, --log-level LOG_LEVEL
|
|
80
80
|
log level to use (default: info, possible levels:
|
|
81
81
|
debug, info, warning, error, critical)
|
|
82
82
|
-i, --incremental incremental backup
|
|
83
|
-
--incremental-by-files
|
|
83
|
+
--incremental-by-files
|
|
84
|
+
incremental backup based on modification date of files
|
|
84
85
|
--starred include JSON output of starred repositories in backup
|
|
85
86
|
--all-starred include starred repositories in backup [*]
|
|
87
|
+
--starred-skip-size-over MB
|
|
88
|
+
skip starred repositories larger than this size in MB
|
|
86
89
|
--watched include JSON output of watched repositories in backup
|
|
87
90
|
--followers include JSON output of followers in backup
|
|
88
91
|
--following include JSON output of following users in backup
|
|
@@ -100,20 +103,22 @@ CLI Help output::
|
|
|
100
103
|
--milestones include milestones in backup
|
|
101
104
|
--repositories include repository clone in backup
|
|
102
105
|
--bare clone bare repositories
|
|
106
|
+
--no-prune disable prune option for git fetch
|
|
103
107
|
--lfs clone LFS repositories (requires Git LFS to be
|
|
104
108
|
installed, https://git-lfs.github.com) [*]
|
|
105
109
|
--wikis include wiki clone in backup
|
|
106
110
|
--gists include gists in backup [*]
|
|
107
111
|
--starred-gists include starred gists in backup [*]
|
|
112
|
+
--skip-archived skip project if it is archived
|
|
108
113
|
--skip-existing skip project if a backup directory exists
|
|
109
|
-
-L
|
|
114
|
+
-L, --languages [LANGUAGES ...]
|
|
110
115
|
only allow these languages
|
|
111
|
-
-N
|
|
116
|
+
-N, --name-regex NAME_REGEX
|
|
112
117
|
python regex to match names against
|
|
113
|
-
-H
|
|
118
|
+
-H, --github-host GITHUB_HOST
|
|
114
119
|
GitHub Enterprise hostname
|
|
115
120
|
-O, --organization whether or not this is an organization user
|
|
116
|
-
-R
|
|
121
|
+
-R, --repository REPOSITORY
|
|
117
122
|
name of repository to limit backup to
|
|
118
123
|
-P, --private include private repositories [*]
|
|
119
124
|
-F, --fork include forked repositories [*]
|
|
@@ -128,19 +133,16 @@ CLI Help output::
|
|
|
128
133
|
--releases include release information, not including assets or
|
|
129
134
|
binaries
|
|
130
135
|
--latest-releases NUMBER_OF_LATEST_RELEASES
|
|
131
|
-
include certain number of the latest releases;
|
|
132
|
-
|
|
133
|
-
--skip-prerelease skip prerelease and draft versions; only applies if
|
|
136
|
+
include certain number of the latest releases; only
|
|
137
|
+
applies if including releases
|
|
138
|
+
--skip-prerelease skip prerelease and draft versions; only applies if
|
|
139
|
+
including releases
|
|
134
140
|
--assets include assets alongside release information; only
|
|
135
141
|
applies if including releases
|
|
136
|
-
--skip-assets-on [
|
|
137
|
-
skip asset downloads for these repositories
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
to issues/attachments/{issue_number}/ and
|
|
141
|
-
pulls/attachments/{pull_number}/ directories
|
|
142
|
-
--exclude [REPOSITORY [REPOSITORY ...]]
|
|
143
|
-
names of repositories to exclude from backup.
|
|
142
|
+
--skip-assets-on [SKIP_ASSETS_ON ...]
|
|
143
|
+
skip asset downloads for these repositories
|
|
144
|
+
--attachments download user-attachments from issues and pull
|
|
145
|
+
requests
|
|
144
146
|
--throttle-limit THROTTLE_LIMIT
|
|
145
147
|
start throttling of GitHub API requests after this
|
|
146
148
|
amount of API requests remain
|
|
@@ -148,6 +150,8 @@ CLI Help output::
|
|
|
148
150
|
wait this amount of seconds when API request
|
|
149
151
|
throttling is active (default: 30.0, requires
|
|
150
152
|
--throttle-limit to be set)
|
|
153
|
+
--exclude [EXCLUDE ...]
|
|
154
|
+
names of repositories to exclude
|
|
151
155
|
|
|
152
156
|
|
|
153
157
|
Usage Details
|
|
@@ -156,13 +160,13 @@ Usage Details
|
|
|
156
160
|
Authentication
|
|
157
161
|
--------------
|
|
158
162
|
|
|
159
|
-
|
|
163
|
+
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/>`_.
|
|
160
164
|
|
|
161
|
-
|
|
165
|
+
The positional argument ``USER`` specifies the user or organization account you wish to back up.
|
|
162
166
|
|
|
163
|
-
**
|
|
167
|
+
**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.
|
|
164
168
|
|
|
165
|
-
|
|
169
|
+
**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.
|
|
166
170
|
|
|
167
171
|
|
|
168
172
|
Fine Tokens
|
|
@@ -290,10 +294,20 @@ All is not everything
|
|
|
290
294
|
|
|
291
295
|
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.
|
|
292
296
|
|
|
293
|
-
|
|
294
|
-
|
|
297
|
+
Starred repository size
|
|
298
|
+
-----------------------
|
|
299
|
+
|
|
300
|
+
Using the ``--all-starred`` argument to clone all starred repositories may use a large amount of storage space.
|
|
301
|
+
|
|
302
|
+
To see your starred repositories sorted by size (requires `GitHub CLI <https://cli.github.com>`_)::
|
|
303
|
+
|
|
304
|
+
gh api user/starred --paginate --jq 'sort_by(-.size)[]|"\(.full_name) \(.size/1024|round)MB"'
|
|
305
|
+
|
|
306
|
+
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.
|
|
307
|
+
|
|
308
|
+
For finer control, avoid using ``--assets`` with starred repos, or use ``--skip-assets-on`` for specific repositories with large release binaries.
|
|
295
309
|
|
|
296
|
-
|
|
310
|
+
Alternatively, consider just storing links to starred repos in JSON format with ``--starred``.
|
|
297
311
|
|
|
298
312
|
Incremental Backup
|
|
299
313
|
------------------
|
|
@@ -36,23 +36,26 @@ Show the CLI help output::
|
|
|
36
36
|
|
|
37
37
|
CLI Help output::
|
|
38
38
|
|
|
39
|
-
github-backup [-h] [-
|
|
40
|
-
[-
|
|
41
|
-
[-
|
|
42
|
-
[--
|
|
43
|
-
[--
|
|
39
|
+
github-backup [-h] [-t TOKEN_CLASSIC] [-f TOKEN_FINE] [-q] [--as-app]
|
|
40
|
+
[-o OUTPUT_DIRECTORY] [-l LOG_LEVEL] [-i]
|
|
41
|
+
[--incremental-by-files]
|
|
42
|
+
[--starred] [--all-starred] [--starred-skip-size-over MB]
|
|
43
|
+
[--watched] [--followers] [--following] [--all]
|
|
44
|
+
[--issues] [--issue-comments] [--issue-events] [--pulls]
|
|
44
45
|
[--pull-comments] [--pull-commits] [--pull-details]
|
|
45
46
|
[--labels] [--hooks] [--milestones] [--repositories]
|
|
46
|
-
[--bare] [--
|
|
47
|
-
[--
|
|
48
|
-
[-
|
|
49
|
-
[-P] [-F] [--prefer-ssh] [-v]
|
|
47
|
+
[--bare] [--no-prune] [--lfs] [--wikis] [--gists]
|
|
48
|
+
[--starred-gists] [--skip-archived] [--skip-existing]
|
|
49
|
+
[-L [LANGUAGES ...]] [-N NAME_REGEX] [-H GITHUB_HOST]
|
|
50
|
+
[-O] [-R REPOSITORY] [-P] [-F] [--prefer-ssh] [-v]
|
|
50
51
|
[--keychain-name OSX_KEYCHAIN_ITEM_NAME]
|
|
51
52
|
[--keychain-account OSX_KEYCHAIN_ITEM_ACCOUNT]
|
|
52
53
|
[--releases] [--latest-releases NUMBER_OF_LATEST_RELEASES]
|
|
53
|
-
[--skip-prerelease] [--assets]
|
|
54
|
-
[--
|
|
55
|
-
[--throttle-limit THROTTLE_LIMIT]
|
|
54
|
+
[--skip-prerelease] [--assets]
|
|
55
|
+
[--skip-assets-on [SKIP_ASSETS_ON ...]] [--attachments]
|
|
56
|
+
[--throttle-limit THROTTLE_LIMIT]
|
|
57
|
+
[--throttle-pause THROTTLE_PAUSE]
|
|
58
|
+
[--exclude [EXCLUDE ...]]
|
|
56
59
|
USER
|
|
57
60
|
|
|
58
61
|
Backup a github account
|
|
@@ -60,29 +63,29 @@ CLI Help output::
|
|
|
60
63
|
positional arguments:
|
|
61
64
|
USER github username
|
|
62
65
|
|
|
63
|
-
|
|
66
|
+
options:
|
|
64
67
|
-h, --help show this help message and exit
|
|
65
|
-
-
|
|
66
|
-
username for basic auth
|
|
67
|
-
-p PASSWORD, --password PASSWORD
|
|
68
|
-
password for basic auth. If a username is given but
|
|
69
|
-
not a password, the password will be prompted for.
|
|
70
|
-
-f TOKEN_FINE, --token-fine TOKEN_FINE
|
|
71
|
-
fine-grained personal access token or path to token
|
|
72
|
-
(file://...)
|
|
73
|
-
-t TOKEN_CLASSIC, --token TOKEN_CLASSIC
|
|
68
|
+
-t, --token TOKEN_CLASSIC
|
|
74
69
|
personal access, OAuth, or JSON Web token, or path to
|
|
75
70
|
token (file://...)
|
|
71
|
+
-f, --token-fine TOKEN_FINE
|
|
72
|
+
fine-grained personal access token (github_pat_....),
|
|
73
|
+
or path to token (file://...)
|
|
74
|
+
-q, --quiet supress log messages less severe than warning, e.g.
|
|
75
|
+
info
|
|
76
76
|
--as-app authenticate as github app instead of as a user.
|
|
77
|
-
-o
|
|
77
|
+
-o, --output-directory OUTPUT_DIRECTORY
|
|
78
78
|
directory at which to backup the repositories
|
|
79
|
-
-l
|
|
79
|
+
-l, --log-level LOG_LEVEL
|
|
80
80
|
log level to use (default: info, possible levels:
|
|
81
81
|
debug, info, warning, error, critical)
|
|
82
82
|
-i, --incremental incremental backup
|
|
83
|
-
--incremental-by-files
|
|
83
|
+
--incremental-by-files
|
|
84
|
+
incremental backup based on modification date of files
|
|
84
85
|
--starred include JSON output of starred repositories in backup
|
|
85
86
|
--all-starred include starred repositories in backup [*]
|
|
87
|
+
--starred-skip-size-over MB
|
|
88
|
+
skip starred repositories larger than this size in MB
|
|
86
89
|
--watched include JSON output of watched repositories in backup
|
|
87
90
|
--followers include JSON output of followers in backup
|
|
88
91
|
--following include JSON output of following users in backup
|
|
@@ -100,20 +103,22 @@ CLI Help output::
|
|
|
100
103
|
--milestones include milestones in backup
|
|
101
104
|
--repositories include repository clone in backup
|
|
102
105
|
--bare clone bare repositories
|
|
106
|
+
--no-prune disable prune option for git fetch
|
|
103
107
|
--lfs clone LFS repositories (requires Git LFS to be
|
|
104
108
|
installed, https://git-lfs.github.com) [*]
|
|
105
109
|
--wikis include wiki clone in backup
|
|
106
110
|
--gists include gists in backup [*]
|
|
107
111
|
--starred-gists include starred gists in backup [*]
|
|
112
|
+
--skip-archived skip project if it is archived
|
|
108
113
|
--skip-existing skip project if a backup directory exists
|
|
109
|
-
-L
|
|
114
|
+
-L, --languages [LANGUAGES ...]
|
|
110
115
|
only allow these languages
|
|
111
|
-
-N
|
|
116
|
+
-N, --name-regex NAME_REGEX
|
|
112
117
|
python regex to match names against
|
|
113
|
-
-H
|
|
118
|
+
-H, --github-host GITHUB_HOST
|
|
114
119
|
GitHub Enterprise hostname
|
|
115
120
|
-O, --organization whether or not this is an organization user
|
|
116
|
-
-R
|
|
121
|
+
-R, --repository REPOSITORY
|
|
117
122
|
name of repository to limit backup to
|
|
118
123
|
-P, --private include private repositories [*]
|
|
119
124
|
-F, --fork include forked repositories [*]
|
|
@@ -128,19 +133,16 @@ CLI Help output::
|
|
|
128
133
|
--releases include release information, not including assets or
|
|
129
134
|
binaries
|
|
130
135
|
--latest-releases NUMBER_OF_LATEST_RELEASES
|
|
131
|
-
include certain number of the latest releases;
|
|
132
|
-
|
|
133
|
-
--skip-prerelease skip prerelease and draft versions; only applies if
|
|
136
|
+
include certain number of the latest releases; only
|
|
137
|
+
applies if including releases
|
|
138
|
+
--skip-prerelease skip prerelease and draft versions; only applies if
|
|
139
|
+
including releases
|
|
134
140
|
--assets include assets alongside release information; only
|
|
135
141
|
applies if including releases
|
|
136
|
-
--skip-assets-on [
|
|
137
|
-
skip asset downloads for these repositories
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
to issues/attachments/{issue_number}/ and
|
|
141
|
-
pulls/attachments/{pull_number}/ directories
|
|
142
|
-
--exclude [REPOSITORY [REPOSITORY ...]]
|
|
143
|
-
names of repositories to exclude from backup.
|
|
142
|
+
--skip-assets-on [SKIP_ASSETS_ON ...]
|
|
143
|
+
skip asset downloads for these repositories
|
|
144
|
+
--attachments download user-attachments from issues and pull
|
|
145
|
+
requests
|
|
144
146
|
--throttle-limit THROTTLE_LIMIT
|
|
145
147
|
start throttling of GitHub API requests after this
|
|
146
148
|
amount of API requests remain
|
|
@@ -148,6 +150,8 @@ CLI Help output::
|
|
|
148
150
|
wait this amount of seconds when API request
|
|
149
151
|
throttling is active (default: 30.0, requires
|
|
150
152
|
--throttle-limit to be set)
|
|
153
|
+
--exclude [EXCLUDE ...]
|
|
154
|
+
names of repositories to exclude
|
|
151
155
|
|
|
152
156
|
|
|
153
157
|
Usage Details
|
|
@@ -156,13 +160,13 @@ Usage Details
|
|
|
156
160
|
Authentication
|
|
157
161
|
--------------
|
|
158
162
|
|
|
159
|
-
|
|
163
|
+
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/>`_.
|
|
160
164
|
|
|
161
|
-
|
|
165
|
+
The positional argument ``USER`` specifies the user or organization account you wish to back up.
|
|
162
166
|
|
|
163
|
-
**
|
|
167
|
+
**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.
|
|
164
168
|
|
|
165
|
-
|
|
169
|
+
**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.
|
|
166
170
|
|
|
167
171
|
|
|
168
172
|
Fine Tokens
|
|
@@ -290,10 +294,20 @@ All is not everything
|
|
|
290
294
|
|
|
291
295
|
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.
|
|
292
296
|
|
|
293
|
-
|
|
294
|
-
|
|
297
|
+
Starred repository size
|
|
298
|
+
-----------------------
|
|
299
|
+
|
|
300
|
+
Using the ``--all-starred`` argument to clone all starred repositories may use a large amount of storage space.
|
|
301
|
+
|
|
302
|
+
To see your starred repositories sorted by size (requires `GitHub CLI <https://cli.github.com>`_)::
|
|
303
|
+
|
|
304
|
+
gh api user/starred --paginate --jq 'sort_by(-.size)[]|"\(.full_name) \(.size/1024|round)MB"'
|
|
305
|
+
|
|
306
|
+
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.
|
|
307
|
+
|
|
308
|
+
For finer control, avoid using ``--assets`` with starred repos, or use ``--skip-assets-on`` for specific repositories with large release binaries.
|
|
295
309
|
|
|
296
|
-
|
|
310
|
+
Alternatively, consider just storing links to starred repos in JSON format with ``--starred``.
|
|
297
311
|
|
|
298
312
|
Incremental Backup
|
|
299
313
|
------------------
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.59.0"
|
|
@@ -43,7 +43,7 @@ def main():
|
|
|
43
43
|
if args.private and not get_auth(args):
|
|
44
44
|
logger.warning(
|
|
45
45
|
"The --private flag has no effect without authentication. "
|
|
46
|
-
"Use -t/--token
|
|
46
|
+
"Use -t/--token or -f/--token-fine to authenticate."
|
|
47
47
|
)
|
|
48
48
|
|
|
49
49
|
if args.quiet:
|