Metadata-Version: 2.4
Name: easyborg
Version: 0.9.6
Summary: Borg for Dummies
Author-email: Sebastian Haberey <sebastian@haberey.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/sebastianhaberey/easyborg
Project-URL: Repository, https://github.com/sebastianhaberey/easyborg
Project-URL: Bug Tracker, https://github.com/sebastianhaberey/easyborg/issues
Project-URL: Changelog, https://github.com/sebastianhaberey/easyborg/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.3.1
Requires-Dist: cloup>=3.0.8
Requires-Dist: rich>=14.2.0
Requires-Dist: platformdirs>=4.5.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.1; extra == "dev"
Requires-Dist: ruff>=0.14.5; extra == "dev"
Dynamic: license-file

# Easyborg

Easyborg is a simple frontend for the awesome [BorgBackup](https://www.borgbackup.org/) (aka Borg)
with [fzf](https://github.com/junegunn/fzf) for user input.

This project is currently in beta phase.

[![Tests (Linux)](https://github.com/sebastianhaberey/easyborg/actions/workflows/tests-linux.yml/badge.svg)](https://github.com/sebastianhaberey/easyborg/actions/workflows/tests-linux.yml)
[![Tests (macOS)](https://github.com/sebastianhaberey/easyborg/actions/workflows/tests-macos.yml/badge.svg)](https://github.com/sebastianhaberey/easyborg/actions/workflows/tests-macos.yml)

## Screenshots

### Extract

<img src="https://raw.githubusercontent.com/sebastianhaberey/easyborg/main/documentation/images/extract.gif" width="1024"  alt="Extract command in terminal"/>

### Backup

<img src="https://raw.githubusercontent.com/sebastianhaberey/easyborg/main/documentation/images/backup.gif" width="1024"  alt="Backup command in terminal"/>

## Setup

### Installation

You have the choice between Homebrew / Linuxbrew or Python pipx.

#### Homebrew / Linuxbrew (recommended)

```
brew tap sebastianhaberey/easyborg
brew install easyborg
```

#### pipx

```
pipx install easyborg 
```

> **NOTE** You'll need a Python installation for pipx. Also make sure you
> have [BorgBackup](https://www.borgbackup.org/)
> and [fzf](https://github.com/junegunn/fzf) installed.

### Repositories

Easyborg doesn't provide any commands for creating repositories. It's easy to do with Borg, and you only have to do
it once. For Easyborg to access a repository, Borg commands must work on it **without** having to enter a password:

```
$ borg list /Volumes/STICK/backup
2025-11-13T17:46:47-F1AC35F6         Thu, 2025-11-13 17:46:47 [7b9fd68dd8e991ea9fd598ca015e10266498afc156969ccdfe67149124fd27cc]
2025-11-14T20:20:25-2965DCFB         Fri, 2025-11-14 20:20:25 [33539a1e5f2b83852cf5396ed442531d6b5d4cb2137522280285725c3ea5df48]
```

- If you're asked for a SSH password, set up access to your server via SSH key.
- If you're asked for a Borg repository password,
  [set up BORG_PASSCOMMAND](https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables).

> **NOTE** Any repository you want to use with Easyborg should be accessible on your terminal **without** password
> request.

### Configuration

Call _easyborg info_ to generate a config file with some demo settings and show its path:

```
$ easyborg info

Configuration:

  Config dir    /Users/user/Library/Application Support/easyborg/default
  Config file   /Users/user/Library/Application Support/easyborg/default/easyborg.toml
  Log dir       /Users/user/Library/Logs/easyborg/default
  Log file      /Users/user/Library/Logs/easyborg/default/easyborg.log
  Log level     INFO
  
...

```

If you're on a modern terminal, you may be able to click on a path to open it (Ctrl + click on iTerm2).
Open the config file, keep and change the settings you like, delete those that you don't need.

## Usage

Easyborg currently supports five main commands: _backup_, _archive_, _restore_, _extract_ and _delete_. Use

```
$ easyborg --help
```

for details.

## Concept

Easyborg makes a distinction between _backup_ and _archive_.

|             | Purpose                                    | Data Type         | Retention        |
|-------------|--------------------------------------------|-------------------|------------------|
| **Backup**  | Recovery in case of emergency (short-term) | Current, changing | Days to months   |
| **Archive** | Preservation for reference (long-term)     | Old, stable       | Years or forever |

### Backup

If you enable automatic backups, Easyborg will create a snapshot of all configured folders in each configured
**backup repository** every full hour. Meaning at 12:00, 13:00 and so on. Then, snapshots are pruned to save space.
So after the 13:00 snapshot is written, the 12:00 snapshot will be deleted. Here's how snapshots are retained:

- the last snapshot of the day for the past seven days
- one snapshot per week for the past three months

Any snapshot older than three months will be deleted.

> **NOTE** Pruning only occurs when _easyborg backup_ is called, manually or automatically.
> If you don't call it, your existing snapshots won't be touched.

### Archive

With Easyborg you create a snapshot in each configured **archive repository** whenever you want. For example if
you decide to tidy up your _Documents_ folder, a resonable strategy would be:

1. Delete all files you want to get rid of (especially big files)
2. Archive the remaining files using _easyborg archive_
3. Delete all files you want to keep but don't need for your daily work

That way, you start with a nice clean slate and still have all the documents you might need for later reference
stored away in your archive repositories. Of course you can follow a different approach. It's up to you what to archive
and when.

> **NOTE** Archive snapshots are never pruned automatically. If you want to delete an archive snapshot, use _easyborg
delete_.

### Relativization

If you _backup_ or _archive_ a folder, e.g.:

```
/Users/user/Documents
```

it will be stored in the snapshot as:

```
Users/user/Documents
```

When you _restore_ or _extract_ the folder, it will be written to the current working directory:

```
<CWD>/Users/user/Documents
```

This is a safety feature. If you _do_ want to overwrite the original folder, you can

- go to its parent folder (/ in the example) and run the restore action there, or
- remove the original folder and move the restored one (recommended)

### Glossary

| Easyborg           | Meaning                                                         | Borg             |
|--------------------|-----------------------------------------------------------------|------------------|
| Snapshot           | immutable point-in-time view of data                            | Archive          |
| Backup Repository  | storage of snapshots intended for recovery                      | Repository       |
| Archive Repository | storage of snapshots intended for preservation                  | Repository       |
| Snapshot Location  | Borg-style snapshot reference (`repository_url::snapshot_name`) | Archive Location |
| Repository URL     | Borg-style repository reference (local or remote)               | (same)           |
| backup (command)   | create snapshot in backup repository                            | `borg create`    |
| archive (command)  | create snapshot in archive repository                           | `borg create`    |
| extract (command)  | fetch selected items from snapshot                              | `borg extract`   | 
| restore (command)  | fetch entire snapshot                                           | `borg extract`   |

## Disclaimer

Even though I'm doing my best, and there's an automatic test suite that covers the critical functionality on Linux and
macOS, errors can happen. Use this application at your own risk. It is highly recommended to start with fresh
repositories to avoid data loss.
