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 ```