bev 0.11.5

Description:

bev 0.11.5

Flexible version control for files and folders.
Install
The simplest way is to get it from PyPi:
pip install bev

Cheatsheet
Adding new files
ls
# image.png ids.json some-folder
bev add image.png
ls
# image.png.hash ids.json some-folder
bev add ids.json some-folder
ls
# image.png.hash ids.json.hash some-folder.hash

git add image.png.hash ids.json.hash some-folder.hash
git commit -m "added new files"

Restoring the hashed files and folders
ls
# image.png.hash ids.json.hash some-folder.hash
bev pull image.png.hash --mode copy
ls
# image.png ids.json.hash some-folder.hash
bev pull some-folder.hash --mode copy
ls
# image.png ids.json.hash some-folder

Browsing a hashed folder
In this recipe we "expand" the hashed folder and fill it with the hashes of the files it contains.
This is much faster than copying back the entire folder.
ls
# image.png.hash ids.json.hash some-folder.hash
bev pull some-folder.hash --mode hash
ls
# image.png.hash ids.json.hash some-folder
ls some-folder
# photo.jpg.hash some-text-file.txt.hash nested-folder

Afterwards you can add the folder back
bev add some-folder
ls
# image.png.hash ids.json.hash some-folder.hash

Getting started

Choose a folder for your repository and create a basic config (.bev.yml):

main:
storage: /path/to/storage/folder

meta:
hash: sha256


Run init

bev init


Add files to bev

bev add /path/to/some/file.json
# also can provide several paths
bev add /path/to/some/folder/ /path/to/some/image.png


... and to git

git add file.json.hash folder.hash image.png.hash
git commit -m "added files"


Access the files from python

import imageio
from bev import Repository

# `version` can be a commit hash or a git tag
repo = Repository('/path/to/repo', version='8a7fe6')
image = imageio.imread(repo.resolve('image.png'))


Or from cli

# replace the folder's hash by the hashes of its files
bev pull folder.hash --mode hash
# entirely restore the folder (inverse of `bev add folder`)
bev pull folder.hash --mode copy
# same for files
bev pull image.png.hash --mode copy

Advanced usage
Here are some tutorials that cover more advanced configuration, including multiple storage locations and machines:

Create a repository - needed only at first time setup
Adding files
Accessing files

Why not DVC?
DVC is a great project, and we took inspiration from it while designing bev.
However, out lab has several requirements that DVC doesn't meet:

Our data caches are spread across multiple HDDs - we need support for multiple cache locations
We have multiple machines, and each of them has a different storage configuration: locations, number of HDDs, their
volumes - we need a flexible way of choosing the right config depending on the machine
Often we simultaneously conduct experiments on different versions of the same data - we need easy access to multiple
version of the same data
The need for dvc checkout after git checkout is error-prone, because it can lead to situations when the data is
not consistent with the current commit - we need a more constrained relation between data and git

bev supports all four out of the box!
However, if these requirements are not essential to your project, you may want to stick with DVC - its community and
tests coverage is much larger.