Resolves #10 via a new verb: gsb export which supports creating an archive of any revision in the Git history in either zip or tar (including compressed tar) format.
This module is licensed under GPLv2, as it borrows heavily from code existing in the GPLv2-licensed pygit2 library
This allows export.export_backup to support for creating tar and zip archives, applying the appropriate format and compression based on the specified filename (which, in lieu of user-specification, is programmatically generated)
Exposes a gsb export CLI that has support for specifying the archive format implicitly via filename or explicitly using a series of mutually-exclusive flags (which is a pain in the toucans to do with Click (see: https://github.com/pallets/click/issues/257)
I did look into using click-option-group but I must have been doing something wrong, because neither the documentation nor the actual mutual-exclusion checking were working as intended.
Tech Debt and Other Concerns
gsb export can be slow (for example, exporting a 3GB backup to a tar.xz). I don't believe tarfile supports multithreading, and I don't even know for certain that it doesn't require holding the entire tarball in memory during compression. Probably the best practice for power-users will be to export as uncompressed tar and then use xz standalone to perform the compression. This is something I may play with.
Export does not support ZIP archives that contain symlinks. That's a limitation of the zipfile library (see: https://bugs.python.org/issue37921). Given that ZIP is the default format for Windows users, I'm hoping that symlinks-in-backups is relatively rare / something that's easily mitigated by using a format flag.
Validation Performed
Used the CLI to create backups of this project's Git repo at various tags and commits
generally this will error out for non-GSB repos, but if you provide the filename, it won't actually check for a manifest)
Used the CLI to create an auto-named archive of an actual GSB-managed repo
[x] need to triple-check that Finder uncompresses .tar.gz files out-of-the-box with a single click. If that's not the case, I'll have to switch their default to either .tgz or .zip.
[x] I have run mkdocs serve locally and ensured that all API docs and
changes I have made to the static pages are rendering correctly, with all links
working
[x] All tech debt concerns have been resolved, documented as issues, or otherwise
accepted
Very pleased--and only slightly surprised--that all the various compression options are supported on Windows--I would not have been shocked if I needed to xfail some of those tests.
Summary
Resolves #10 via a new verb:
gsb export
which supports creating an archive of any revision in the Git history in either zip or tar (including compressed tar) format.List of Changes
git archive
implementation to the codebase that supports Zip files (see: https://github.com/libgit2/pygit2/issues/1239)export.export_backup
to support for creating tar and zip archives, applying the appropriate format and compression based on the specified filename (which, in lieu of user-specification, is programmatically generated)gsb export
CLI that has support for specifying the archive format implicitly via filename or explicitly using a series of mutually-exclusive flags (which is a pain in the toucans to do with Click (see: https://github.com/pallets/click/issues/257)Tech Debt and Other Concerns
gsb export
can be slow (for example, exporting a 3GB backup to atar.xz
). I don't believetarfile
supports multithreading, and I don't even know for certain that it doesn't require holding the entire tarball in memory during compression. Probably the best practice for power-users will be to export as uncompressed tar and then usexz
standalone to perform the compression. This is something I may play with.Export does not support ZIP archives that contain symlinks. That's a limitation of the
zipfile
library (see: https://bugs.python.org/issue37921). Given that ZIP is the default format for Windows users, I'm hoping that symlinks-in-backups is relatively rare / something that's easily mitigated by using a format flag.Validation Performed
.tar.gz
files out-of-the-box with a single click. If that's not the case, I'll have to switch their default to either.tgz
or.zip
.PR Type
release
)Checklist:
mkdocs serve
locally and ensured that all API docs and changes I have made to the static pages are rendering correctly, with all links working~~[ ] I agree to license my contribution to this project under the GNU Public License v3~~
Technically GPLv2 is incompatible with GPLv3, which is part of the reason I've kept the module fully separate.