Release version 0.19.2

Pull Details

CHANGES.rst

@@ -1,6 +1,225 @@
 Changelog
 =========
 
+0.19.2 (2018-03-24)
+-------------------
+
+Fix
+~~~
+
+- Cleanup pep8 violations. [Jose Diaz-Gonzalez]
+
+0.19.0 (2018-03-24)
+-------------------
+
+- Add additional output for the current request. [Robin Gloster]
+
+  This is useful to have some progress indication for huge repositories.
+
+
+- Add option to backup additional PR details. [Robin Gloster]
+
+  Some payload is only included when requesting a single pull request
+
+
+- Mark string as binary in comparison for skip_existing. [Johannes
+  Bornhold]
+
+  Found out that the flag "--skip-existing" did not work out as expected on Python
+  3.6. Tracked it down to the comparison which has to be against a string of bytes
+  in Python3.
+
+
+0.18.0 (2018-02-22)
+-------------------
+
+- Add option to fetch followers/following JSON data. [Stephen Greene]
+
+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)
+-------------------
+
+- Add OS check for OSX specific keychain args. [Martin O'Reilly]
+
+  Keychain arguments are only supported on Mac OSX.
+  Added check for operating system so we give a
+  "Keychain arguments are only supported on Mac OSX"
+  error message rather than a "No password item matching the
+  provided name and account could be found in the osx keychain"
+  error message
+
+
+- Add support for storing PAT in OSX keychain. [Martin O'Reilly]
+
+  Added additional optional arguments and README guidance for storing
+  and accessing a Github personal access token (PAT) in the OSX
+  keychain
+
+
+0.12.1 (2017-03-27)
+-------------------
+
+- Avoid remote branch name churn. [Chris Adams]
+
+  This avoids the backup output having lots of "[new branch]" messages
+  because removing the old remote name removed all of the existing branch
+  references.
+
+
+- Fix detection of bare git directories. [Andrzej Maczuga]
+
+0.12.0 (2016-11-22)
+-------------------
+
+Fix
+~~~
+
+- Properly import version from github_backup package. [Jose Diaz-
+  Gonzalez]
+
+- Support alternate git status output. [Jose Diaz-Gonzalez]
+
+Other
+~~~~~
+
+- Pep8: E501 line too long (83 > 79 characters) [Jose Diaz-Gonzalez]
+
+- Pep8: E128 continuation line under-indented for visual indent. [Jose
+  Diaz-Gonzalez]
+
+- Support archivization using bare git clones. [Andrzej Maczuga]
+
+- Fix typo, 3x. [Terrell Russell]
+
+0.11.0 (2016-10-26)
+-------------------
+
+- Support --token file:///home/user/token.txt (fixes gh-51) [Björn
+  Dahlgren]
+
+- Fix some linting. [Albert Wang]
+
+- Fix byte/string conversion for python 3. [Albert Wang]
+
+- Support python 3. [Albert Wang]
+
+- Encode special characters in password. [Remi Rampin]
+
+- Don't pretend program name is "Github Backup" [Remi Rampin]
+
+- Don't install over insecure connection. [Remi Rampin]
+
+  The git:// protocol is unauthenticated and unencrypted, and no longer advertised by GitHub. Using HTTPS shouldn't impact performance.
+
+0.10.3 (2016-08-21)
+-------------------
+
+- Fixes #29. [Jonas Michel]
+
+  Reporting an error when the user's rate limit is exceeded causes
+  the script to terminate after resuming execution from a rate limit
+  sleep. Instead of generating an explicit error we just want to
+  inform the user that the script is going to sleep until their rate
+  limit count resets.
+
+
+- Fixes #29. [Jonas Michel]
+
+  The errors list was not being cleared out after resuming a backup
+  from a rate limit sleep. When the backup was resumed, the non-empty
+  errors list caused the backup to quit after the next `retrieve_data`
+  request.
+
+
+0.10.2 (2016-08-21)
+-------------------
+
+- Add a note regarding git version requirement. [Jose Diaz-Gonzalez]
+
+  Closes #37
+
+0.10.0 (2016-08-18)
+-------------------
+
+- Implement incremental updates. [Robert Bradshaw]
+
+  Guarded with an --incremental flag.
+
+  Stores the time of the last update and only downloads issue and
+  pull request data since this time.  All other data is relatively
+  small (likely fetched with a single request) and so is simply
+  re-populated from scratch as before.
+
+
+0.9.0 (2016-03-29)
+------------------
+
+- Fix cloning private repos with basic auth or token. [Kazuki Suda]
+
+0.8.0 (2016-02-14)
+------------------
+
+- Don't store issues which are actually pull requests. [Enrico Tröger]
+
+  This prevents storing pull requests twice since the Github API returns
+  pull requests also as issues. Those issues will be skipped but only if
+  retrieving pull requests is requested as well.
+  Closes #23.
+
+
 0.7.0 (2016-02-02)
 ------------------
 

README.rst

@@ -2,8 +2,15 @@
 github-backup
 =============
 
+|PyPI| |Python Versions|
+
 backup a github user or organization
 
+Requirements
+============
+
+- GIT 1.9+
+
 Installation
 ============
 
@@ -13,22 +20,26 @@ Using PIP via PyPI::
 
 Using PIP via Github::
 
-    pip install git+git://github.com/josegonzalez/python-github-backup.git#egg=github-backup
+    pip install git+https://github.com/josegonzalez/python-github-backup.git#egg=github-backup
 
 Usage
 =====
 
 CLI Usage is as follows::
 
-    Github Backup [-h] [-u USERNAME] [-p PASSWORD] [-t TOKEN]
+    github-backup [-h] [-u USERNAME] [-p PASSWORD] [-t TOKEN]
-                     [-o OUTPUT_DIRECTORY] [--starred] [--watched] [--all]
+                  [-o OUTPUT_DIRECTORY] [-i] [--starred] [--all-starred]
-                     [--issues] [--issue-comments] [--issue-events] [--pulls]
+                  [--watched] [--followers] [--following] [--all]
-                     [--pull-comments] [--pull-commits] [--labels] [--hooks]
+                  [--issues] [--issue-comments] [--issue-events] [--pulls]
-                     [--milestones] [--repositories] [--wikis]
+                  [--pull-comments] [--pull-commits] [--labels] [--hooks]
-                     [--skip-existing] [-L [LANGUAGES [LANGUAGES ...]]]
+                  [--milestones] [--repositories] [--bare] [--lfs]
-                     [-N NAME_REGEX] [-H GITHUB_HOST] [-O] [-R REPOSITORY]
+                  [--wikis] [--gists] [--starred-gists] [--skip-existing]
-                     [-P] [-F] [--prefer-ssh] [-v]
+                  [-L [LANGUAGES [LANGUAGES ...]]] [-N NAME_REGEX]
-                     USER
+                  [-H GITHUB_HOST] [-O] [-R REPOSITORY] [-P] [-F]
+                  [--prefer-ssh] [-v]
+                  [--keychain-name OSX_KEYCHAIN_ITEM_NAME]
+                  [--keychain-account OSX_KEYCHAIN_ITEM_ACCOUNT]
+                  USER
 
     Backup a github account
 
@@ -43,11 +54,16 @@ CLI Usage is as follows::
                             password for basic auth. If a username is given but
                             not a password, the password will be prompted for.
       -t TOKEN, --token TOKEN
-                            personal access or OAuth token
+                            personal access or OAuth token, or path to token
+                            (file://...)
       -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
                             directory at which to backup the repositories
-      --starred             include starred repositories in backup
+      -i, --incremental     incremental backup
+      --starred             include JSON output of starred repositories in backup
+      --all-starred         include starred repositories in backup
       --watched             include watched repositories in backup
+      --followers           include JSON output of followers in backup
+      --following           include JSON output of following users in backup
       --all                 include everything in backup
       --issues              include issues in backup
       --issue-comments      include issue comments in backup
@@ -60,7 +76,12 @@ CLI Usage is as follows::
                             authenticated)
       --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
+      --gists               include gists in backup
+      --starred-gists       include starred gists in backup
       --skip-existing       skip project if a backup directory exists
       -L [LANGUAGES [LANGUAGES ...]], --languages [LANGUAGES [LANGUAGES ...]]
                             only allow these languages
@@ -75,6 +96,12 @@ CLI Usage is as follows::
       -F, --fork            include forked repositories
       --prefer-ssh          Clone repositories using SSH instead of HTTPS
       -v, --version         show program's version number and exit
+      --keychain-name OSX_KEYCHAIN_ITEM_NAME
+                            OSX ONLY: name field of password item in OSX keychain
+                            that holds the personal access or OAuth token
+      --keychain-account OSX_KEYCHAIN_ITEM_ACCOUNT
+                            OSX ONLY: account field of password item in OSX
+                            keychain that holds the personal access or OAuth token
 
 
 The package can be used to backup an *entire* organization or repository, including issues and wikis in the most appropriate format (clones for wikis, json files for issues).
@@ -83,3 +110,46 @@ Authentication
 ==============
 
 Note: Password-based authentication will fail if you have two-factor authentication enabled.
+
+Using the Keychain on Mac OSX
+=============================
+Note: On Mac OSX the token can be stored securely in the user's keychain. To do this:
+
+1. Open Keychain from "Applications -> Utilities -> Keychain Access"
+2. Add a new password item using "File -> New Password Item"
+3. Enter a name in the "Keychain Item Name" box. You must provide this name to github-backup using the --keychain-name argument.
+4. Enter an account name in the "Account Name" box, enter your Github username as set above. You must provide this name to github-backup using the --keychain-account argument.
+5. Enter your Github personal access token in the "Password" box
+
+Note:  When you run github-backup, you will be asked whether you want to allow "security" to use your confidential information stored in your keychain. You have two options:
+
+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

@@ -16,8 +16,23 @@ import select
 import subprocess
 import sys
 import time
-import urllib
+import platform
-import urllib2
+try:
+    # python 3
+    from urllib.parse import urlparse
+    from urllib.parse import quote as urlquote
+    from urllib.parse import urlencode
+    from urllib.error import HTTPError, URLError
+    from urllib.request import urlopen
+    from urllib.request import Request
+except ImportError:
+    # python 2
+    from urlparse import urlparse
+    from urllib import quote as urlquote
+    from urllib import urlencode
+    from urllib2 import HTTPError, URLError
+    from urllib2 import urlopen
+    from urllib2 import Request
 
 from github_backup import __version__
 
@@ -54,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],
                                       [],
                                       [],
@@ -79,8 +98,8 @@ def logging_subprocess(popenargs,
     rc = child.wait()
 
     if rc != 0:
-        print(u'{} returned {}:'.format(popenargs[0], rc), file=sys.stderr)
+        print('{} returned {}:'.format(popenargs[0], rc), file=sys.stderr)
-        print('\t', u' '.join(popenargs), file=sys.stderr)
+        print('\t', ' '.join(popenargs), file=sys.stderr)
 
     return rc
 
@@ -96,9 +115,19 @@ def mkdir_p(*args):
                 raise
 
 
+def mask_password(url, secret='*****'):
+    parsed = urlparse(url)
+
+    if not parsed.password:
+        return url
+    elif parsed.password == 'x-oauth-basic':
+        return url.replace(parsed.username, secret)
+
+    return url.replace(parsed.password, secret)
+
+
 def parse_args():
-    parser = argparse.ArgumentParser(description='Backup a github account',
+    parser = argparse.ArgumentParser(description='Backup a github account')
-                                     prog='Github Backup')
     parser.add_argument('user',
                         metavar='USER',
                         type=str,
@@ -116,20 +145,37 @@ def parse_args():
     parser.add_argument('-t',
                         '--token',
                         dest='token',
-                        help='personal access or OAuth token')
+                        help='personal access or OAuth token, or path to token (file://...)')  # noqa
     parser.add_argument('-o',
                         '--output-directory',
                         default='.',
                         dest='output_directory',
                         help='directory at which to backup the repositories')
+    parser.add_argument('-i',
+                        '--incremental',
+                        action='store_true',
+                        dest='incremental',
+                        help='incremental backup')
     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',
                         dest='include_watched',
                         help='include watched repositories in backup')
+    parser.add_argument('--followers',
+                        action='store_true',
+                        dest='include_followers',
+                        help='include JSON output of followers in backup')
+    parser.add_argument('--following',
+                        action='store_true',
+                        dest='include_following',
+                        help='include JSON output of following users in backup')
     parser.add_argument('--all',
                         action='store_true',
                         dest='include_everything',
@@ -158,6 +204,10 @@ def parse_args():
                         action='store_true',
                         dest='include_pull_commits',
                         help='include pull request commits in backup')
+    parser.add_argument('--pull-details',
+                        action='store_true',
+                        dest='include_pull_details',
+                        help='include more pull request details in backup')
     parser.add_argument('--labels',
                         action='store_true',
                         dest='include_labels',
@@ -165,7 +215,7 @@ def parse_args():
     parser.add_argument('--hooks',
                         action='store_true',
                         dest='include_hooks',
-                        help='include hooks in backup (works only when authenticated)')
+                        help='include hooks in backup (works only when authenticated)')  # noqa
     parser.add_argument('--milestones',
                         action='store_true',
                         dest='include_milestones',
@@ -174,10 +224,26 @@ def parse_args():
                         action='store_true',
                         dest='include_repository',
                         help='include repository clone in backup')
+    parser.add_argument('--bare',
+                        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',
@@ -218,22 +284,60 @@ def parse_args():
     parser.add_argument('-v', '--version',
                         action='version',
                         version='%(prog)s ' + __version__)
+    parser.add_argument('--keychain-name',
+                        dest='osx_keychain_item_name',
+                        help='OSX ONLY: name field of password item in OSX keychain that holds the personal access or OAuth token')
+    parser.add_argument('--keychain-account',
+                        dest='osx_keychain_item_account',
+                        help='OSX ONLY: account field of password item in OSX keychain that holds the personal access or OAuth token')
     return parser.parse_args()
 
 
-def get_auth(args):
+def get_auth(args, encode=True):
-    if args.token:
+    auth = None
-        return base64.b64encode(args.token + ':' + 'x-oauth-basic')
 
-    if args.username:
+    if args.osx_keychain_item_name:
+        if not args.osx_keychain_item_account:
+            log_error('You must specify both name and account fields for osx keychain password items')
+        else:
+            if platform.system() != 'Darwin':
+                log_error("Keychain arguments are only supported on Mac OSX")
+            try:
+                with open(os.devnull, 'w') as devnull:
+                    token = (subprocess.check_output([
+                        'security', 'find-generic-password',
+                        '-s', args.osx_keychain_item_name,
+                        '-a', args.osx_keychain_item_account,
+                        '-w'], stderr=devnull).strip())
+                auth = token + ':' + 'x-oauth-basic'
+            except:
+                log_error('No password item matching the provided name and account could be found in the osx keychain.')
+    elif args.osx_keychain_item_account:
+        log_error('You must specify both name and account fields for osx keychain password items')
+    elif args.token:
+        _path_specifier = 'file://'
+        if args.token.startswith(_path_specifier):
+            args.token = open(args.token[len(_path_specifier):],
+                              'rt').readline().strip()
+        auth = args.token + ':' + 'x-oauth-basic'
+    elif args.username:
         if not args.password:
             args.password = getpass.getpass()
-        return base64.b64encode(args.username + ':' + args.password)
+        if encode:
-
+            password = args.password
-    if args.password:
+        else:
+            password = urlquote(args.password)
+        auth = args.username + ':' + password
+    elif args.password:
         log_error('You must specify a username for basic auth')
 
-    return None
+    if not auth:
+        return None
+
+    if not encode:
+        return auth
+
+    return base64.b64encode(auth.encode('ascii'))
 
 
 def get_github_api_host(args):
@@ -245,7 +349,7 @@ def get_github_api_host(args):
     return host
 
 
-def get_github_ssh_host(args):
+def get_github_host(args):
     if args.github_host:
         host = args.github_host
     else:
@@ -254,6 +358,26 @@ def get_github_ssh_host(args):
     return host
 
 
+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),
+            repository['owner']['login'],
+            repository['name'])
+    else:
+        repo_url = repository['clone_url']
+
+    return repo_url
+
+
 def retrieve_data(args, template, query_args=None, single_request=False):
     auth = get_auth(args)
     query_args = get_query_args(query_args)
@@ -273,7 +397,7 @@ def retrieve_data(args, template, query_args=None, single_request=False):
             errors.append(template.format(status_code, r.reason))
             log_error(errors)
 
-        response = json.loads(r.read())
+        response = json.loads(r.read().decode('utf-8'))
         if len(errors) == 0:
             if type(response) == list:
                 data.extend(response)
@@ -305,11 +429,11 @@ def _get_response(request, auth, template):
     while True:
         should_continue = False
         try:
-            r = urllib2.urlopen(request)
+            r = urlopen(request)
-        except urllib2.HTTPError as exc:
+        except HTTPError as exc:
             errors, should_continue = _request_http_error(exc, auth, errors)  # noqa
             r = exc
-        except urllib2.URLError:
+        except URLError:
             should_continue = _request_url_error(template, retry_timeout)
             if not should_continue:
                 raise
@@ -322,14 +446,15 @@ def _get_response(request, auth, template):
 
 
 def _construct_request(per_page, page, query_args, template, auth):
-    querystring = urllib.urlencode(dict({
+    querystring = urlencode(dict(list({
         'per_page': per_page,
         'page': page
-    }.items() + query_args.items()))
+    }.items()) + list(query_args.items())))
 
-    request = urllib2.Request(template + '?' + querystring)
+    request = Request(template + '?' + querystring)
     if auth is not None:
-        request.add_header('Authorization', 'Basic ' + auth)
+        request.add_header('Authorization', 'Basic '.encode('ascii') + auth)
+    log_info('Requesting {}?{}'.format(template, querystring))
     return request
 
 
@@ -356,10 +481,9 @@ def _request_http_error(exc, auth, errors):
         print('Exceeded rate limit of {} requests; waiting {} seconds to reset'.format(limit, delta),  # noqa
               file=sys.stderr)
 
-        ratelimit_error = 'No more requests remaining'
         if auth is None:
-            ratelimit_error += '; authenticate to raise your GitHub rate limit'  # noqa
+            print('Hint: Authenticate to raise your GitHub rate limit',
-        errors.append(ratelimit_error)
+                  file=sys.stderr)
 
         time.sleep(delta)
         should_continue = True
@@ -379,6 +503,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
@@ -396,13 +527,44 @@ 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, repositories):
+def filter_repositories(args, unfiltered_repositories):
     log_info('Filtering repositories')
 
-    repositories = [r for r in repositories if r['owner']['login'] == args.user]
+    repositories = []
+    for r in unfiltered_repositories:
+        # 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
     if args.name_regex:
@@ -413,11 +575,11 @@ def filter_repositories(args, 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'])]
 
@@ -428,28 +590,56 @@ def backup_repositories(args, output_directory, repositories):
     log_info('Backing up repositories')
     repos_template = 'https://{0}/repos'.format(get_github_api_host(args))
 
-    for repository in repositories:
+    if args.incremental:
-        backup_cwd = os.path.join(output_directory, 'repositories')
+        last_update = max(list(repository['updated_at'] for repository in repositories) or [time.strftime('%Y-%m-%dT%H:%M:%SZ', time.localtime())])  # noqa
-        repo_cwd = os.path.join(backup_cwd, repository['name'])
+        last_update_path = os.path.join(output_directory, 'last_update')
-        repo_dir = os.path.join(repo_cwd, 'repository')
+        if os.path.exists(last_update_path):
-
+            args.since = open(last_update_path).read().strip()
-        if args.prefer_ssh:
-            repo_url = repository['ssh_url']
         else:
-            repo_url = repository['clone_url']
+            args.since = None
+    else:
+        args.since = None
 
-        if args.include_repository or args.include_everything:
+    for repository in repositories:
-            fetch_repository(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)
+
+        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)
+                             skip_existing=args.skip_existing,
+                             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:
             fetch_repository(repository['name'],
                              repo_url.replace('.git', '.wiki.git'),
                              os.path.join(repo_cwd, 'wiki'),
-                             skip_existing=args.skip_existing)
+                             skip_existing=args.skip_existing,
+                             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)
@@ -466,6 +656,9 @@ def backup_repositories(args, output_directory, repositories):
         if args.include_hooks or args.include_everything:
             backup_hooks(args, repo_cwd, repository, repos_template)
 
+    if args.incremental:
+        open(last_update_path, 'w').write(last_update)
+
 
 def backup_issues(args, repo_cwd, repository, repos_template):
     has_issues_dir = os.path.isdir('{0}/issues/.git'.format(repo_cwd))
@@ -477,26 +670,42 @@ def backup_issues(args, repo_cwd, repository, repos_template):
     mkdir_p(repo_cwd, issue_cwd)
 
     issues = {}
+    issues_skipped = 0
+    issues_skipped_message = ''
     _issue_template = '{0}/{1}/issues'.format(repos_template,
                                               repository['full_name'])
 
+    should_include_pulls = args.include_pulls or args.include_everything
     issue_states = ['open', 'closed']
     for issue_state in issue_states:
         query_args = {
             'filter': 'all',
             'state': issue_state
         }
+        if args.since:
+            query_args['since'] = args.since
 
         _issues = retrieve_data(args,
                                 _issue_template,
                                 query_args=query_args)
         for issue in _issues:
+            # skip pull requests which are also returned as issues
+            # if retrieving pull requests is requested as well
+            if 'pull_request' in issue and should_include_pulls:
+                issues_skipped += 1
+                continue
+
             issues[issue['number']] = issue
 
-    log_info('Saving {0} issues to disk'.format(len(issues.keys())))
+    if issues_skipped:
+        issues_skipped_message = ' (skipped {0} pull requests)'.format(
+            issues_skipped)
+
+    log_info('Saving {0} issues to disk{1}'.format(
+        len(list(issues.keys())), issues_skipped_message))
     comments_template = _issue_template + '/{0}/comments'
     events_template = _issue_template + '/{0}/events'
-    for number, issue in issues.iteritems():
+    for number, issue in list(issues.items()):
         if args.include_issue_comments or args.include_everything:
             template = comments_template.format(number)
             issues[number]['comment_data'] = retrieve_data(args, template)
@@ -521,24 +730,41 @@ def backup_pulls(args, repo_cwd, repository, repos_template):
     pulls = {}
     _pulls_template = '{0}/{1}/pulls'.format(repos_template,
                                              repository['full_name'])
+    query_args = {
+        'filter': 'all',
+        'state': 'all',
+        'sort': 'updated',
+        'direction': 'desc',
+    }
 
-    pull_states = ['open', 'closed']
+    if not args.include_pull_details:
-    for pull_state in pull_states:
+        pull_states = ['open', 'closed']
-        query_args = {
+        for pull_state in pull_states:
-            'filter': 'all',
+            query_args['state'] = pull_state
-            'state': pull_state
+            # It'd be nice to be able to apply the args.since filter here...
-        }
+            _pulls = retrieve_data(args,
-
+                                   _pulls_template,
+                                   query_args=query_args)
+            for pull in _pulls:
+                if not args.since or pull['updated_at'] >= args.since:
+                    pulls[pull['number']] = pull
+    else:
         _pulls = retrieve_data(args,
                                _pulls_template,
                                query_args=query_args)
         for pull in _pulls:
-            pulls[pull['number']] = pull
+            if not args.since or pull['updated_at'] >= args.since:
+                pulls[pull['number']] = retrieve_data(
+                    args,
+                    _pulls_template + '/{}'.format(pull['number']),
+                    single_request=True
+                )
 
-    log_info('Saving {0} pull requests to disk'.format(len(pulls.keys())))
+    log_info('Saving {0} pull requests to disk'.format(
+        len(list(pulls.keys()))))
     comments_template = _pulls_template + '/{0}/comments'
     commits_template = _pulls_template + '/{0}/commits'
-    for number, pull in pulls.iteritems():
+    for number, pull in list(pulls.items()):
         if args.include_pull_comments or args.include_everything:
             template = comments_template.format(number)
             pulls[number]['comment_data'] = retrieve_data(args, template)
@@ -572,8 +798,9 @@ def backup_milestones(args, repo_cwd, repository, repos_template):
     for milestone in _milestones:
         milestones[milestone['number']] = milestone
 
-    log_info('Saving {0} milestones to disk'.format(len(milestones.keys())))
+    log_info('Saving {0} milestones to disk'.format(
-    for number, milestone in milestones.iteritems():
+        len(list(milestones.keys()))))
+    for number, milestone in list(milestones.items()):
         milestone_file = '{0}/{1}.json'.format(milestone_cwd, number)
         with codecs.open(milestone_file, 'w', encoding='utf-8') as f:
             json_dump(milestone, f)
@@ -599,7 +826,7 @@ def backup_hooks(args, repo_cwd, repository, repos_template):
     hook_cwd = os.path.join(repo_cwd, 'hooks')
     output_file = '{0}/hooks.json'.format(hook_cwd)
     template = '{0}/{1}/hooks'.format(repos_template,
-                                       repository['full_name'])
+                                      repository['full_name'])
     try:
         _backup_data(args,
                      'hooks',
@@ -610,33 +837,73 @@ def backup_hooks(args, repo_cwd, repository, repos_template):
         log_info("Unable to read hooks, skipping")
 
 
-def fetch_repository(name, remote_url, local_dir, skip_existing=False):
+def fetch_repository(name,
-    clone_exists = os.path.exists(os.path.join(local_dir, '.git'))
+                     remote_url,
+                     local_dir,
+                     skip_existing=False,
+                     bare_clone=False,
+                     lfs_clone=False):
+    if bare_clone:
+        if os.path.exists(local_dir):
+            clone_exists = subprocess.check_output(['git',
+                                                    'rev-parse',
+                                                    '--is-bare-repository'],
+                                                   cwd=local_dir) == b"true\n"
+        else:
+            clone_exists = False
+    else:
+        clone_exists = os.path.exists(os.path.join(local_dir, '.git'))
 
     if clone_exists and skip_existing:
         return
 
-    initalized = subprocess.call('git ls-remote ' + remote_url,
+    masked_remote_url = mask_password(remote_url)
-                                 stdout=FNULL,
+
-                                 stderr=FNULL,
+    initialized = subprocess.call('git ls-remote ' + remote_url,
-                                 shell=True)
+                                  stdout=FNULL,
-    if initalized == 128:
+                                  stderr=FNULL,
-        log_info("Skipping {0} ({1}) since it's not initalized".format(name, remote_url))
+                                  shell=True)
+    if initialized == 128:
+        log_info("Skipping {0} ({1}) since it's not initialized".format(
+            name, masked_remote_url))
         return
 
     if clone_exists:
         log_info('Updating {0} in {1}'.format(name, local_dir))
-        git_command = ['git', 'remote', 'rm', 'origin']
+
-        logging_subprocess(git_command, None, cwd=local_dir)
+        remotes = subprocess.check_output(['git', 'remote', 'show'],
-        git_command = ['git', 'remote', 'add', 'origin', remote_url]
+                                          cwd=local_dir)
-        logging_subprocess(git_command, None, cwd=local_dir)
+        remotes = [i.strip() for i in remotes.decode('utf-8').splitlines()]
-        git_command = ['git', 'fetch', '--all', '--tags', '--prune']
+
+        if 'origin' not in remotes:
+            git_command = ['git', 'remote', 'rm', 'origin']
+            logging_subprocess(git_command, None, cwd=local_dir)
+            git_command = ['git', 'remote', 'add', 'origin', remote_url]
+            logging_subprocess(git_command, None, cwd=local_dir)
+        else:
+            git_command = ['git', 'remote', 'set-url', 'origin', remote_url]
+            logging_subprocess(git_command, None, cwd=local_dir)
+
+        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(name,
+        log_info('Cloning {0} repository from {1} to {2}'.format(
-                                                                 remote_url,
+            name,
-                                                                 local_dir))
+            masked_remote_url,
-        git_command = ['git', 'clone', remote_url, local_dir]
+            local_dir))
+        if bare_clone:
+            if lfs_clone:
+                git_command = ['git', 'lfs', 'clone', '--mirror', remote_url, local_dir]
+            else:
+                git_command = ['git', 'clone', '--mirror', remote_url, local_dir]
+        else:
+            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)
 
 
@@ -644,21 +911,37 @@ def backup_account(args, output_directory):
     account_cwd = os.path.join(output_directory, 'account')
 
     if args.include_starred or args.include_everything:
-        output_file = '{0}/starred.json'.format(account_cwd)
+        output_file = "{0}/starred.json".format(account_cwd)
-        template = "https://{0}/users/{1}/starred"
+        template = "https://{0}/users/{1}/starred".format(get_github_api_host(args), args.user)
-        template = template.format(get_github_api_host(args), args.user)
         _backup_data(args,
-                     'starred repositories',
+                     "starred repositories",
                      template,
                      output_file,
                      account_cwd)
 
     if args.include_watched or args.include_everything:
-        output_file = '{0}/watched.json'.format(account_cwd)
+        output_file = "{0}/watched.json".format(account_cwd)
-        template = "https://{0}/users/{1}/subscriptions"
+        template = "https://{0}/users/{1}/subscriptions".format(get_github_api_host(args), args.user)
-        template = template.format(get_github_api_host(args), args.user)
         _backup_data(args,
-                     'watched repositories',
+                     "watched repositories",
+                     template,
+                     output_file,
+                     account_cwd)
+
+    if args.include_followers or args.include_everything:
+        output_file = "{0}/followers.json".format(account_cwd)
+        template = "https://{0}/users/{1}/followers".format(get_github_api_host(args), args.user)
+        _backup_data(args,
+                     "followers",
+                     template,
+                     output_file,
+                     account_cwd)
+
+    if args.include_following or args.include_everything:
+        output_file = "{0}/following.json".format(account_cwd)
+        template = "https://{0}/users/{1}/following".format(get_github_api_host(args), args.user)
+        _backup_data(args,
+                     "following",
                      template,
                      output_file,
                      account_cwd)
@@ -693,6 +976,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.7.0'
+__version__ = '0.19.2'

release

@@ -34,7 +34,7 @@ fi
 echo -e "\n${GREEN}STARTING RELEASE PROCESS${COLOR_OFF}\n"
 
 set +e;
-git status | grep "working directory clean" &> /dev/null
+git status | grep -Eo "working (directory|tree) clean" &> /dev/null
 if [ ! $? -eq 0 ]; then # working directory is NOT clean
     echo -e "${RED}WARNING: You have uncomitted changes, you may have forgotten something${COLOR_OFF}\n"
     exit 1

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(),