diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d239f2a --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +.mypy_cache + +__pycache__/ +*.pyc + +.*.swp +.*.swo + +build/ +dist/ + +*.egg-info/ diff --git a/README.md b/README.md index 5f50a98..acebc58 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,45 @@ # lethe README -```lethe``` is a Python module for git-based snapshotting. +`lethe` is a Python module for git-based snapshotting. -```lethe``` is intended as a mechanism for creating commits outside +`lethe` is intended as a mechanism for creating commits outside the standard git branching/tagging workflows. It is meant to enable additional use-cases without disrupting the standard workflows. Use cases include: - Short-lived: - On-disk **undo log** - - **Syncing work-in-progress** between computers before it's ready + - **Syncing work-in-progress** between computers before it's ready - Long-lived: - **lab notebook**: Recording the code / configuration state that resulted in a given output - - **incremental backup**: Space-efficient time-based backups of a codebase + - **incremental backup**: Space-efficient time-based backups of a codebase ## Usage -### Creating a commit from the command line +### Creating a commit from the command line ```bash $ cd path/to/repo $ lethe 122d058e375274a186c407f28602c3b14a2cab95 ``` This effectively snapshots the current state of the repository (as would be seen by -```git add --all```) and creates a new commit (```122d058e375274a186c407f28602c3b14a2cab95```) +`git add --all`) and creates a new commit (`122d058e375274a186c407f28602c3b14a2cab95`) which points to it. The current branch and index are not changed. ### Flags: -- ```-p my_parent_ref``` is used to provide "parent" refs which become the parents of the created commit. +- `-p my_parent_ref` is used to provide "parent" refs which become the parents of the created commit. If a parent ref is a symbolic ref, *both* the provided ref and the ref it points to are used as parents. -If not present, defaults to ```-p HEAD```. -- ```-t ref/lethe/my_target_ref``` is used to provide "target" refs which will be created/updated +If not present, defaults to `-p HEAD`. +- `-t ref/lethe/my_target_ref` is used to provide "target" refs which will be created/updated to point to the created commit. -If not present, defaults to adding an entry of the form ```-t refs/lethe/my_branch``` for each -parent ref of the form ```refs/heads/my_branch```, and ```-t refs/lethe/my/refpath``` for non-head -refs of the form ```refs/my/refpath```. All provided parent refs *and* any dereferenced parent refs +If not present, defaults to adding an entry of the form `-t refs/lethe/my_branch` for each +parent ref of the form `refs/heads/my_branch`, and `-t refs/lethe/my/refpath` for non-head +refs of the form `refs/my/refpath`. All provided parent refs *and* any dereferenced parent refs are used to generate default target refs. If any of the target refs already exist, the commits they point to become parents of the created commit. -- ```-m "my message"``` sets the commit message for the snapshot. By default, "snapshot " is used. -- ```-r path/to/repo``` can be provided to specify a repository outside of the current working directory. +- `-m "my message"` sets the commit message for the snapshot. By default, "snapshot " is used. +- `-r path/to/repo` can be provided to specify a repository outside of the current working directory. ```bash $ cd path/to/repo @@ -73,9 +73,9 @@ print('Code (tree) state is ' + tree_sha) Requirements: * python 3 (written and tested with 3.6) -* git (accessible on the system ```PATH```) +* git (accessible on the system `PATH`) Install with pip: ```bash -pip install lethe +pip3 install lethe ``` diff --git a/TODO b/TODO new file mode 100644 index 0000000..46491eb --- /dev/null +++ b/TODO @@ -0,0 +1 @@ +VERSION file? diff --git a/__pycache__/lethe.cpython-37.pyc b/__pycache__/lethe.cpython-37.pyc deleted file mode 100644 index 0b60d13..0000000 Binary files a/__pycache__/lethe.cpython-37.pyc and /dev/null differ diff --git a/lethe.egg-info/PKG-INFO b/lethe.egg-info/PKG-INFO deleted file mode 100644 index d59fbbd..0000000 --- a/lethe.egg-info/PKG-INFO +++ /dev/null @@ -1,102 +0,0 @@ -Metadata-Version: 2.1 -Name: lethe -Version: 0.7 -Summary: Git-based snapshotting -Home-page: https://mpxd.net/code/jan/lethe -Author: Jan Petykiewicz -Author-email: anewusername@gmail.com -License: UNKNOWN -Description: # lethe README - - ```lethe``` is a Python module for git-based snapshotting. - - ```lethe``` is intended as a mechanism for creating commits outside - the standard git branching/tagging workflows. It is meant to enable - additional use-cases without disrupting the standard workflows. - Use cases include: - - - Short-lived: - - On-disk **undo log** - - **Syncing work-in-progress** between computers before it's ready - - Long-lived: - - **lab notebook**: Recording the code / configuration state that resulted in a given output - - **incremental backup**: Space-efficient time-based backups of a codebase - - - ## Usage - - ### Creating a commit from the command line - ```bash - $ cd path/to/repo - $ lethe - 122d058e375274a186c407f28602c3b14a2cab95 - ``` - This effectively snapshots the current state of the repository (as would be seen by - ```git add --all```) and creates a new commit (```122d058e375274a186c407f28602c3b14a2cab95```) - which points to it. The current branch and index are not changed. - - ### Flags: - - ```-p my_parent_ref``` is used to provide "parent" refs which become the parents of the created commit. - If a parent ref is a symbolic ref, *both* the provided ref and the ref it points to are used as parents. - If not present, defaults to ```-p HEAD```. - - ```-t ref/lethe/my_target_ref``` is used to provide "target" refs which will be created/updated - to point to the created commit. - If not present, defaults to adding an entry of the form ```-t refs/lethe/my_branch``` for each - parent ref of the form ```refs/heads/my_branch```, and ```-t refs/lethe/my/refpath``` for non-head - refs of the form ```refs/my/refpath```. All provided parent refs *and* any dereferenced parent refs - are used to generate default target refs. - If any of the target refs already exist, the commits they point to become parents of the created commit. - - ```-m "my message"``` sets the commit message for the snapshot. By default, "snapshot " is used. - - ```-r path/to/repo``` can be provided to specify a repository outside of the current working directory. - - ```bash - $ cd path/to/repo - $ git branch - * master - $ lethe - ``` - is equivalent to - ```bash - lethe -r path/to/repo -p HEAD - ``` - or - ```bash - lethe -r path/to/repo -p HEAD -p refs/heads/master -t refs/lethe/HEAD -t refs/lethe/master - ``` - - ### Creating a commit programmatically - ```python - import lethe - REPO = '/path/to/repo' - - commit_sha = lethe.snap(cwd=REPO) - tree_sha = lethe.get_tree(commit_sha, cwd=REPO) - - print('Created new commit with hash ' + commit_sha + ' aka refs/lethe/HEAD') - print('Code (tree) state is ' + tree_sha) - ``` - - - ## Installation - - Requirements: - * python 3 (written and tested with 3.6) - * git (accessible on the system ```PATH```) - - Install with pip: - ```bash - pip install lethe - ``` - -Keywords: git,snapshot,commit,refs,backup,undo,log,lab notebook,traceability -Platform: UNKNOWN -Classifier: Programming Language :: Python -Classifier: Programming Language :: Python :: 3 -Classifier: Development Status :: 4 - Beta -Classifier: Environment :: Other Environment -Classifier: Intended Audience :: Developers -Classifier: Intended Audience :: Science/Research -Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3) -Classifier: Topic :: Software Development :: Version Control :: Git -Classifier: Topic :: Utilities -Description-Content-Type: text/markdown diff --git a/lethe.egg-info/SOURCES.txt b/lethe.egg-info/SOURCES.txt deleted file mode 100644 index bb5a57b..0000000 --- a/lethe.egg-info/SOURCES.txt +++ /dev/null @@ -1,9 +0,0 @@ -README.md -lethe.py -setup.py -lethe.egg-info/PKG-INFO -lethe.egg-info/SOURCES.txt -lethe.egg-info/dependency_links.txt -lethe.egg-info/entry_points.txt -lethe.egg-info/requires.txt -lethe.egg-info/top_level.txt \ No newline at end of file diff --git a/lethe.egg-info/dependency_links.txt b/lethe.egg-info/dependency_links.txt deleted file mode 100644 index 8b13789..0000000 --- a/lethe.egg-info/dependency_links.txt +++ /dev/null @@ -1 +0,0 @@ - diff --git a/lethe.egg-info/entry_points.txt b/lethe.egg-info/entry_points.txt deleted file mode 100644 index 684a58a..0000000 --- a/lethe.egg-info/entry_points.txt +++ /dev/null @@ -1,3 +0,0 @@ -[console_scripts] -lethe = lethe:main - diff --git a/lethe.egg-info/requires.txt b/lethe.egg-info/requires.txt deleted file mode 100644 index c997f36..0000000 --- a/lethe.egg-info/requires.txt +++ /dev/null @@ -1 +0,0 @@ -typing diff --git a/lethe.egg-info/top_level.txt b/lethe.egg-info/top_level.txt deleted file mode 100644 index 713adee..0000000 --- a/lethe.egg-info/top_level.txt +++ /dev/null @@ -1 +0,0 @@ -lethe diff --git a/lethe/VERSION.py b/lethe/VERSION.py new file mode 100644 index 0000000..032341c --- /dev/null +++ b/lethe/VERSION.py @@ -0,0 +1,4 @@ +""" VERSION defintion. THIS FILE IS MANUALLY PARSED BY setup.py and REQUIRES A SPECIFIC FORMAT """ +__version__ = ''' +0.9 +''' diff --git a/lethe/__init__.py b/lethe/__init__.py new file mode 100644 index 0000000..337e2b9 --- /dev/null +++ b/lethe/__init__.py @@ -0,0 +1,12 @@ +""" +Git snapshotting tool +""" +from .lethe import ( + main, snap, snap_ref, snap_tree, find_merge_base, deref_symref, + update_ref, commit_tree, get_tree, get_commit, get_obj, get_root, get_latest_commit, + shorten_hash, _run, + ) + +from .VERSION import __version__ + +__author__ = 'Jan Petykeiwicz' diff --git a/lethe/__main__.py b/lethe/__main__.py new file mode 100644 index 0000000..ff534a2 --- /dev/null +++ b/lethe/__main__.py @@ -0,0 +1,4 @@ +from .lethe import main + +if __name__ == '__main__': + main() diff --git a/lethe.py b/lethe/lethe.py similarity index 98% rename from lethe.py rename to lethe/lethe.py index 6154516..a1ac0c2 100755 --- a/lethe.py +++ b/lethe/lethe.py @@ -3,20 +3,16 @@ Git snapshotting tool """ +from typing import List, Union import subprocess import tempfile import datetime import argparse from itertools import chain -from typing import List import sys -__author__ = 'Jan Petykeiwicz' -version = 0.7 - - -def _run(command: str or List[str], **kwargs): +def _run(command: Union[str, List[str]], **kwargs) -> str: """ Wrapper for subprocess.run(): - Accepts args as either a list of strings or space-delimited string diff --git a/lethe/py.typed b/lethe/py.typed new file mode 100644 index 0000000..e69de29 diff --git a/setup.py b/setup.py index 4f65088..8a03a7b 100644 --- a/setup.py +++ b/setup.py @@ -1,19 +1,26 @@ #!/usr/bin/env python3 -from setuptools import setup -import lethe +from setuptools import setup, find_packages -with open('README.md', 'r') as f: + +with open('README.md', 'rt') as f: long_description = f.read() +with open('lethe/VERSION.py', 'rt') as f: + version = f.readlines()[2].strip() + setup(name='lethe', - version=lethe.version, + version=version, description='Git-based snapshotting', long_description=long_description, long_description_content_type='text/markdown', author='Jan Petykiewicz', author_email='anewusername@gmail.com', - py_modules=['lethe'], + url='https://mpxd.net/code/jan/lethe', + packages=find_packages(), + package_data={ + 'lethe': ['py.typed'], + }, entry_points={ 'console_scripts': [ 'lethe=lethe:main', @@ -22,7 +29,6 @@ setup(name='lethe', install_requires=[ 'typing', ], - url='https://mpxd.net/code/jan/lethe', keywords=[ 'git', 'snapshot',