gitstore 0.2.3

Utilities to encrypt files/directories with utilitz and exchange them through GitHub repositories.

gitstore

gitstore is a focused Python package for one goal:

• upload encrypted files/folders to a GitHub-backed repo
• download and restore encrypted GitHub files later

Installation

pip install gitstore

Dependency on utilitz

This project depends on:

• utilitz[crypto]
• requests

Project Structure

gitstore/
  src/gitstore/
    __init__.py
    client.py
    config.py
    crypto_ops.py
    github_ops.py
  pyproject.toml
  README.md

Core API

from gitstore import upload_to_github, restore_from_github, restore_from_file

Upload

from gitstore import upload_to_github

record = upload_to_github(
    source_path="C:/data/documento.pdf",  # file or directory
    name="documento_ventas_q2",           # logical name only
    repo_path="C:/repos/my-publish-repo", # required
    password=None,                        # default: uses GITSTORE_PASSWORD
    vault_dir="vault",                    # default
    request_timeout=60,                   # default
    security_level="high",                # default
    replace_existing=True,                # default
    force=False,                          # default
    commit_message=None,                  # default: automatic message
)
print(record)

Upload behavior:

• computes source_hash from source content before encryption
• skips upload if same name already has same source_hash
• set force=True to upload even when the current source matches the remote metadata
• stores artifact as vault/<name>.asc
• stores metadata in vault/index.json
• removes temporary encrypted file after processing

Valid Names

name is the logical identifier used to upload an artifact. It is intentionally strict to keep Git paths predictable:

• allowed characters: letters, numbers, dots, underscores, and hyphens
• must start with a letter or number
• spaces and path separators are not allowed

Valid examples:

documento_ventas_q2
maindb-version-0.1
backup.2026_05

Invalid examples:

maindb -version 0.1
../secret
folder/documento

Download

from gitstore import restore_from_github

output_path = restore_from_github(
    github_raw_url="https://raw.githubusercontent.com/USER/REPO/main/vault/documento_ventas_q2.asc",
    password=None,      # default: uses GITSTORE_PASSWORD
    output_path=None,   # default: restores in the current working directory
    overwrite=False,    # default
    force=False,        # default
    use_urllib=False,   # default: True uses urllib alternative route
)
print(output_path)

Local restore (no network):

from gitstore import restore_from_file

output_path = restore_from_file(
    encrypted_file_path="C:/downloads/documento_ventas_q2.asc",
    password=None,      # default: uses GITSTORE_PASSWORD
    output_path=None,   # optional
    overwrite=False,    # default
)
print(output_path)

Tip:

• use restore_from_file(...) when the target machine has SSL/certificate restrictions and you prefer manual transfer of the .asc file.

Download behavior:

• expects RAW GitHub URLs (raw.githubusercontent.com/...) as primary input
• also accepts github.com/.../blob/... and normalizes automatically
• skips download when output_path already exists and matches the remote source_hash in vault/index.json
• set force=True to download even when the local output appears aligned
• set use_urllib=True to use the urllib alternative transport path
• downloads the encrypted .asc file to a temporary location
• restores files or directories automatically with utilitz.crypto
• removes the temporary encrypted file after restore
• supports local decode with restore_from_file(...) when manual download is preferred

Password Source

upload_to_github, restore_from_github, and restore_from_file auto-detect password from:

• GITSTORE_PASSWORD

If password is not passed, the environment variable is used.