Release version 0.17.0

Add ability to back up gists

CHANGES.rst

@@ -1,6 +1,60 @@
 Changelog
 =========
 
+0.17.0 (2018-02-20)
+-------------------
+
+- Short circuit gists backup process. [W. Harrison Wright]
+
+- Formatting. [W. Harrison Wright]
+
+- Add ability to backup gists. [W. Harrison Wright]
+
+0.16.0 (2018-01-22)
+-------------------
+
+- Change option to --all-starred. [W. Harrison Wright]
+
+- JK don't update documentation. [W. Harrison Wright]
+
+- Put starred clone repoistories under a new option. [W. Harrison
+  Wright]
+
+- Add comment. [W. Harrison Wright]
+
+- Add ability to clone starred repos. [W. Harrison Wright]
+
+0.14.1 (2017-10-11)
+-------------------
+
+- Fix arg not defined error. [Edward Pfremmer]
+
+  Ref: https://github.com/josegonzalez/python-github-backup/issues/69
+
+0.14.0 (2017-10-11)
+-------------------
+
+- Added a check to see if git-lfs is installed when doing an LFS clone.
+  [pieterclaerhout]
+
+- Added support for LFS clones. [pieterclaerhout]
+
+- Add pypi info to readme. [Albert Wang]
+
+- Explicitly support python 3 in package description. [Albert Wang]
+
+- Add couple examples to help new users. [Yusuf Tran]
+
+0.13.2 (2017-05-06)
+-------------------
+
+- Fix remotes while updating repository. [Dima Gerasimov]
+
+0.13.1 (2017-04-11)
+-------------------
+
+- Fix error when repository has no updated_at value. [Nicolai Ehemann]
+
 0.13.0 (2017-04-05)
 -------------------
 

README.rst

@@ -2,6 +2,8 @@
 github-backup
 =============
 
+|PyPI| |Python Versions|
+
 backup a github user or organization
 
 Requirements
@@ -29,8 +31,9 @@ CLI Usage is as follows::
                   [-o OUTPUT_DIRECTORY] [-i] [--starred] [--watched]
                   [--all] [--issues] [--issue-comments] [--issue-events]
                   [--pulls] [--pull-comments] [--pull-commits] [--labels]
-                  [--hooks] [--milestones] [--repositories] [--bare]
-                  [--wikis] [--skip-existing]
+                  [--hooks] [--milestones] [--repositories] [--bare] [--lfs]
+                  [--wikis] [--skip-existing] [--all-starred]
+                  [--gists] [--starred-gists]
                   [-L [LANGUAGES [LANGUAGES ...]]] [-N NAME_REGEX]
                   [-H GITHUB_HOST] [-O] [-R REPOSITORY] [-P] [-F]
                   [--prefer-ssh] [-v]
@@ -55,7 +58,7 @@ CLI Usage is as follows::
       -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
                             directory at which to backup the repositories
       -i, --incremental     incremental backup
-      --starred             include starred repositories in backup
+      --starred             include JSON output of starred repositories in backup
       --watched             include watched repositories in backup
       --all                 include everything in backup
       --issues              include issues in backup
@@ -70,8 +73,12 @@ CLI Usage is as follows::
       --milestones          include milestones in backup
       --repositories        include repository clone in backup
       --bare                clone bare repositories
+      --lfs                 clone LFS repositories (requires Git LFS to be installed, https://git-lfs.github.com)
       --wikis               include wiki clone in backup
       --skip-existing       skip project if a backup directory exists
+      --all-starred         include starred repositories in backup
+      --gists               include gists in backup
+      --starred-gists       include starred gists in backup
       -L [LANGUAGES [LANGUAGES ...]], --languages [LANGUAGES [LANGUAGES ...]]
                             only allow these languages
       -N NAME_REGEX, --name-regex NAME_REGEX
@@ -114,3 +121,31 @@ Note:  When you run github-backup, you will be asked whether you want to allow "
 
 1. **Allow:** In this case you will need to click "Allow" each time you run `github-backup`
 2. **Always Allow:** In this case, you will not be asked for permission when you run `github-backup` in future. This is less secure, but is required if you want to schedule `github-backup` to run automatically
+
+About Git LFS
+=============
+
+When you use the "--lfs" option, you will need to make sure you have Git LFS installed.
+
+Instructions on how to do this can be found on https://git-lfs.github.com.
+
+Examples
+========
+
+Backup all repositories::
+
+    export ACCESS_TOKEN=SOME-GITHUB-TOKEN
+    github-backup WhiteHouse --token $ACCESS_TOKEN --organization --output-directory /tmp/white-house --repositories
+
+Backup a single organization repository with everything else (wiki, pull requests, comments, issues etc)::
+
+    export ACCESS_TOKEN=SOME-GITHUB-TOKEN
+    ORGANIZATION=docker
+    REPO=cli
+    # e.g. git@github.com:docker/cli.git
+    github-backup $ORGANIZATION -P -t $ACCESS_TOKEN -o . --all -O -R $REPO
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/github-backup.svg
+   :target: https://pypi.python.org/pypi/github-backup/
+.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/github-backup.svg
+   :target: https://github.com/albertyw/github-backup

bin/github-backup

@@ -69,11 +69,15 @@ def logging_subprocess(popenargs,
     """
     child = subprocess.Popen(popenargs, stdout=subprocess.PIPE,
                              stderr=subprocess.PIPE, **kwargs)
+    if sys.platform == 'win32':
+        log_info("Windows operating system detected - no subprocess logging will be returned")
 
     log_level = {child.stdout: stdout_log_level,
                  child.stderr: stderr_log_level}
 
     def check_io():
+        if sys.platform == 'win32':
+            return
         ready_to_read = select.select([child.stdout, child.stderr],
                                       [],
                                       [],
@@ -155,6 +159,10 @@ def parse_args():
     parser.add_argument('--starred',
                         action='store_true',
                         dest='include_starred',
+                        help='include JSON output of starred repositories in backup')
+    parser.add_argument('--all-starred',
+                        action='store_true',
+                        dest='all_starred',
                         help='include starred repositories in backup')
     parser.add_argument('--watched',
                         action='store_true',
@@ -208,10 +216,22 @@ def parse_args():
                         action='store_true',
                         dest='bare_clone',
                         help='clone bare repositories')
+    parser.add_argument('--lfs',
+                        action='store_true',
+                        dest='lfs_clone',
+                        help='clone LFS repositories (requires Git LFS to be installed, https://git-lfs.github.com)')
     parser.add_argument('--wikis',
                         action='store_true',
                         dest='include_wiki',
                         help='include wiki clone in backup')
+    parser.add_argument('--gists',
+                        action='store_true',
+                        dest='include_gists',
+                        help='include gists in backup')
+    parser.add_argument('--starred-gists',
+                        action='store_true',
+                        dest='include_starred_gists',
+                        help='include starred gists in backup')
     parser.add_argument('--skip-existing',
                         action='store_true',
                         dest='skip_existing',
@@ -330,12 +350,15 @@ def get_github_repo_url(args, repository):
     if args.prefer_ssh:
         return repository['ssh_url']
 
+    if repository.get('is_gist'):
+        return repository['git_pull_url']
+
     auth = get_auth(args, False)
     if auth:
         repo_url = 'https://{0}@{1}/{2}/{3}.git'.format(
             auth,
             get_github_host(args),
-            args.user,
+            repository['owner']['login'],
             repository['name'])
     else:
         repo_url = repository['clone_url']
@@ -467,6 +490,13 @@ def _request_url_error(template, retry_timeout):
     return False
 
 
+def check_git_lfs_install():
+    exit_code = subprocess.call(['git', 'lfs', 'version'])
+    if exit_code != 0:
+        log_error('The argument --lfs requires you to have Git LFS installed.\nYou can get it from https://git-lfs.github.com.')
+        sys.exit(1)
+
+
 def retrieve_repositories(args):
     log_info('Retrieving repositories')
     single_request = False
@@ -484,7 +514,34 @@ def retrieve_repositories(args):
             args.user,
             args.repository)
 
-    return retrieve_data(args, template, single_request=single_request)
+    repos = retrieve_data(args, template, single_request=single_request)
+
+    if args.all_starred:
+        starred_template = 'https://{0}/user/starred'.format(get_github_api_host(args))
+        starred_repos = retrieve_data(args, starred_template, single_request=False)
+        # flag each repo as starred for downstream processing
+        for item in starred_repos:
+            item.update({'is_starred': True})
+        repos.extend(starred_repos)
+
+    if args.include_gists:
+        gists_template = 'https://{0}/gists'.format(get_github_api_host(args))
+        gists = retrieve_data(args, gists_template, single_request=False)
+        # flag each repo as a gist for downstream processing
+        for item in gists:
+            item.update({'is_gist': True})
+        repos.extend(gists)
+
+    if args.include_starred_gists:
+        starred_gists_template = 'https://{0}/gists/starred'.format(get_github_api_host(args))
+        starred_gists = retrieve_data(args, starred_gists_template, single_request=False)
+        # flag each repo as a starred gist for downstream processing
+        for item in starred_gists:
+            item.update({'is_gist': True,
+                         'is_starred': True})
+        repos.extend(starred_gists)
+
+    return repos
 
 
 def filter_repositories(args, unfiltered_repositories):
@@ -492,7 +549,8 @@ def filter_repositories(args, unfiltered_repositories):
 
     repositories = []
     for r in unfiltered_repositories:
-        if r['owner']['login'] == args.user:
+        # gists can be anonymous, so need to safely check owner
+        if r.get('owner', {}).get('login') == args.user or r.get('is_starred'):
             repositories.append(r)
 
     name_regex = None
@@ -504,11 +562,11 @@ def filter_repositories(args, unfiltered_repositories):
         languages = [x.lower() for x in args.languages]
 
     if not args.fork:
-        repositories = [r for r in repositories if not r['fork']]
+        repositories = [r for r in repositories if not r.get('fork')]
     if not args.private:
-        repositories = [r for r in repositories if not r['private']]
+        repositories = [r for r in repositories if not r.get('private') or r.get('public')]
     if languages:
-        repositories = [r for r in repositories if r['language'] and r['language'].lower() in languages]  # noqa
+        repositories = [r for r in repositories if r.get('language') and r.get('language').lower() in languages]  # noqa
     if name_regex:
         repositories = [r for r in repositories if name_regex.match(r['name'])]
 
@@ -520,7 +578,7 @@ def backup_repositories(args, output_directory, repositories):
     repos_template = 'https://{0}/repos'.format(get_github_api_host(args))
 
     if args.incremental:
-        last_update = max(repository['updated_at'] for repository in repositories)  # noqa
+        last_update = max(list(repository['updated_at'] for repository in repositories) or [time.strftime('%Y-%m-%dT%H:%M:%SZ', time.localtime())])  # noqa
         last_update_path = os.path.join(output_directory, 'last_update')
         if os.path.exists(last_update_path):
             args.since = open(last_update_path).read().strip()
@@ -530,17 +588,36 @@ def backup_repositories(args, output_directory, repositories):
         args.since = None
 
     for repository in repositories:
-        backup_cwd = os.path.join(output_directory, 'repositories')
-        repo_cwd = os.path.join(backup_cwd, repository['name'])
+        if repository.get('is_gist'):
+            repo_cwd = os.path.join(output_directory, 'gists', repository['id'])
+        elif repository.get('is_starred'):
+            # put starred repos in -o/starred/${owner}/${repo} to prevent collision of
+            # any repositories with the same name
+            repo_cwd = os.path.join(output_directory, 'starred', repository['owner']['login'], repository['name'])
+        else:
+            repo_cwd = os.path.join(output_directory, 'repositories', repository['name'])
+
         repo_dir = os.path.join(repo_cwd, 'repository')
         repo_url = get_github_repo_url(args, repository)
 
-        if args.include_repository or args.include_everything:
-            fetch_repository(repository['name'],
+        include_gists = (args.include_gists or args.include_starred_gists)
+        if (args.include_repository or args.include_everything) \
+                or (include_gists and repository.get('is_gist')):
+            repo_name = repository.get('name') if not repository.get('is_gist') else repository.get('id')
+            fetch_repository(repo_name,
                              repo_url,
                              repo_dir,
                              skip_existing=args.skip_existing,
-                             bare_clone=args.bare_clone)
+                             bare_clone=args.bare_clone,
+                             lfs_clone=args.lfs_clone)
+
+            if repository.get('is_gist'):
+                # dump gist information to a file as well
+                output_file = '{0}/gist.json'.format(repo_cwd)
+                with codecs.open(output_file, 'w', encoding='utf-8') as f:
+                    json_dump(repository, f)
+
+                continue  # don't try to back anything else for a gist; it doesn't exist
 
         download_wiki = (args.include_wiki or args.include_everything)
         if repository['has_wiki'] and download_wiki:
@@ -548,7 +625,8 @@ def backup_repositories(args, output_directory, repositories):
                              repo_url.replace('.git', '.wiki.git'),
                              os.path.join(repo_cwd, 'wiki'),
                              skip_existing=args.skip_existing,
-                             bare_clone=args.bare_clone)
+                             bare_clone=args.bare_clone,
+                             lfs_clone=args.lfs_clone)
 
         if args.include_issues or args.include_everything:
             backup_issues(args, repo_cwd, repository, repos_template)
@@ -738,7 +816,8 @@ def fetch_repository(name,
                      remote_url,
                      local_dir,
                      skip_existing=False,
-                     bare_clone=False):
+                     bare_clone=False,
+                     lfs_clone=False):
     if bare_clone:
         if os.path.exists(local_dir):
             clone_exists = subprocess.check_output(['git',
@@ -769,7 +848,7 @@ def fetch_repository(name,
 
         remotes = subprocess.check_output(['git', 'remote', 'show'],
                                           cwd=local_dir)
-        remotes = [i.strip() for i in remotes.decode('utf-8')]
+        remotes = [i.strip() for i in remotes.decode('utf-8').splitlines()]
 
         if 'origin' not in remotes:
             git_command = ['git', 'remote', 'rm', 'origin']
@@ -780,7 +859,10 @@ def fetch_repository(name,
             git_command = ['git', 'remote', 'set-url', 'origin', remote_url]
             logging_subprocess(git_command, None, cwd=local_dir)
 
-        git_command = ['git', 'fetch', '--all', '--force', '--tags', '--prune']
+        if lfs_clone:
+            git_command = ['git', 'lfs', 'fetch', '--all', '--force', '--tags', '--prune']
+        else:
+            git_command = ['git', 'fetch', '--all', '--force', '--tags', '--prune']
         logging_subprocess(git_command, None, cwd=local_dir)
     else:
         log_info('Cloning {0} repository from {1} to {2}'.format(
@@ -788,9 +870,15 @@ def fetch_repository(name,
             masked_remote_url,
             local_dir))
         if bare_clone:
-            git_command = ['git', 'clone', '--mirror', remote_url, local_dir]
+            if lfs_clone:
+                git_command = ['git', 'lfs', 'clone', '--mirror', remote_url, local_dir]
+            else:
+                git_command = ['git', 'clone', '--mirror', remote_url, local_dir]
         else:
-            git_command = ['git', 'clone', remote_url, local_dir]
+            if lfs_clone:
+                git_command = ['git', 'lfs', 'clone', remote_url, local_dir]
+            else:
+                git_command = ['git', 'clone', remote_url, local_dir]
         logging_subprocess(git_command, None)
 
 
@@ -847,6 +935,9 @@ def main():
         log_info('Create output directory {0}'.format(output_directory))
         mkdir_p(output_directory)
 
+    if args.lfs_clone:
+        check_git_lfs_install()
+
     log_info('Backing up user {0} to {1}'.format(args.user, output_directory))
 
     repositories = retrieve_repositories(args)

github_backup/__init__.py

@@ -1 +1 @@
-__version__ = '0.13.0'
+__version__ = '0.17.0'

setup.py

@@ -39,6 +39,8 @@ setup(
         'License :: OSI Approved :: MIT License',
         'Programming Language :: Python :: 2.6',
         'Programming Language :: Python :: 2.7',
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
     ],
     description='backup a github user or organization',
     long_description=open_file('README.rst').read(),