Metadata-Version: 2.4
Name: gsafe
Version: 0.7.0
Summary: Encrypted portable containers for Git bare remotes.
Project-URL: Homepage, https://github.com/guideblade/gsafe
Project-URL: Repository, https://github.com/guideblade/gsafe
Project-URL: Issues, https://github.com/guideblade/gsafe/issues
Project-URL: Changelog, https://github.com/guideblade/gsafe/blob/main/CHANGELOG.md
Author-email: Nikolay Kulikov <nick@guideblade.ru>
License-Expression: MIT
License-File: LICENSE
Keywords: backup,encryption,git,sync
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: platformdirs>=4.0.0
Description-Content-Type: text/markdown

# GSafe

GSafe stores a Git bare remote as an encrypted `.gsf` container. It allows you to safely store your repository on third party services like Google Drive, and work with it almost as effortlessly as if you were hosting on GitHub. The storage provider cannot read your data, as the unencrypted remote exists only on your device while the container is unlocked.
This tool is not really meant for collaboration. Unlock your containers only on one machine at a time and don't forget to wait until the sync finishes before unlocking it on a second machine.

## Project Status

GSafe is alpha software. The container format and command behavior may still change before a stable `1.0.0` release. Keep independent backups of important repositories.

## Requirements

- Python 3.10 or newer
- Git available in `PATH`
- Git LFS available in `PATH` if the repository uses LFS

The `gsafe` command is a Python console script. It becomes available after the package is installed with a Python package installer. If the Python scripts directory is not in `PATH`, use `python -m gsafe` instead.

## Install

### macOS (recommended)

Python on macOS, especially when installed with Homebrew, may block global `pip` installs with an `externally-managed-environment` error.

For CLI usage, install `gsafe` with `pipx` from inside this repository:

```bash
brew install pipx
pipx install .
```

Check that it works:

```bash
gsafe --version
```

### From this repository

```bash
python3 -m pip install .
```

### For local development

Use a virtual environment so the editable install points to this repository without touching the system Python installation:

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .
```

Check that it works:

```bash
gsafe --version
```

If `gsafe` is not found:

```bash
python3 -m gsafe --version
```

## Platform Notes

macOS and Linux usually expose `python3` and install command-line scripts into a user or virtual environment scripts directory. If `gsafe` is not found after install, either activate the virtual environment you installed it into or use `python3 -m gsafe`.

Windows requires Python 3.10 or newer and Git for Windows. In Git Bash, use `python` or `py -m pip` depending on how Python was installed. If `gsafe.exe` is not in `PATH`, use `python -m gsafe` or add Python's `Scripts` directory to `PATH`.

## Use

```bash
cd ~/path/repo
gsafe init
gsafe status ~/path/repo.gsf
gsafe unlock ~/path/repo.gsf
gsafe lock ~/path/repo.gsf
gsafe change-password ~/path/repo.gsf
```

`gsafe init` uses the current Git repository. You can also pass `--path-repo ~/path/repo` from another directory.
GSafe uses `.gsf` for new containers. It also accepts `.gsafe`. Other extensions require `--force`.
Passing a container path without a command is shorthand for `gsafe status ~/path/repo.gsf`.
`gsafe unlock` and `gsafe lock` also accept `--path-gsafe ~/path/repo.gsf` if you prefer named options.
`gsafe status` asks for the password and prints encrypted container metadata.
`gsafe change-password` asks for the current password once and the new password twice.

## Recovery

If a machine unlocks a container and then becomes unavailable before `gsafe lock`, the container remains marked as unlocked. Recover it from the last encrypted state:

```bash
gsafe recover ~/path/repo.gsf
```

Recovery asks you to type `RECOVER`. It clears the stale unlock marker, but it cannot save commits that existed only in the old unlocked remote.
