From 35dcf438936f66e7f95cd0e1fadcff35a8ac6983 Mon Sep 17 00:00:00 2001 From: Farivar Tabatabaei Date: Sat, 26 Jul 2025 09:41:04 +0330 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20docs:=20Add=20comprehensive?= =?UTF-8?q?=20=F0=9F=9A=80=20quickstart=20guide=20for=20borg-import?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 📌 Add a detailed prerequisites section covering BorgBackup installation, Python 3.9+ requirement, and disk space considerations - 📂 Document basic usage pattern and command structure for all importers - 💡 Provide practical examples for rsnapshot, rsynchl, rsync_tmbackup, and Borg-to-Borg imports with complete workflow steps - ⚙️ Include a common options section covering prefixes, Borg options, and debug mode - 🧠 Explain the smart temporary relocation mechanism that preserves Borg's file cache efficiency and deduplication - 🛡️ Document safety features including non-destructive operations, resume capability, duplicate detection, and journal tracking - 🧯 Add a troubleshooting section for common issues like missing Borg command, interrupted imports, permissions, and disk space - 📖 Provide clear guidance on getting help and next steps for users - ❌ The ".. highlight:: bash" directive has been removed as per it will automatically be included from "global.rst.inc" with ".. include:: global.rst.inc" directive. This quickstart guide serves as a comprehensive introduction that gets users up and running quickly while explaining the underlying mechanics and safety features that make borg-import reliable. --- docs/quickstart.rst | 126 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 125 insertions(+), 1 deletion(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 02fa2a2..da69c11 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,8 +1,132 @@ .. include:: global.rst.inc -.. highlight:: bash .. _quickstart: Quick Start =========== This chapter will get you started with Borg-Import. + +Prerequisites +------------- + +Before using borg-import, you need: + +1. **BorgBackup installed**: borg-import requires the ``borg`` command to be available in your PATH. + Install it following the `BorgBackup installation guide `_. + +2. **Python 3.9 or newer**: borg-import is written in Python and requires a modern Python version. + +3. **Sufficient disk space**: Import operations may require temporary space for intermediate processing. + +Basic Usage Pattern +------------------- + +All borg-import commands follow this general pattern:: + + borg-import [OPTIONS] + +Where: + +- ```` is one of: ``borg``, ``rsnapshot``, ``rsynchl``, or ``rsync_tmbackup`` +- ```` is the path to your existing backup directory or repository +- ```` is the BorgBackup repository where archives will be imported + +**Important**: Always use absolute paths or SSH URLs for repositories to avoid issues during import. + +Quick Examples +-------------- + +**Import from rsnapshot backups**:: + + # Create a new Borg repository first + borg init --encryption=repokey /path/to/new/borg/repo + + # Import rsnapshot backups + borg-import rsnapshot /path/to/rsnapshot/root /path/to/new/borg/repo + +**Import from rsync+hardlinks backups**:: + + # Create a new Borg repository first + borg init --encryption=repokey /path/to/new/borg/repo + + # Import rsync backups + borg-import rsynchl /path/to/rsync/backups /path/to/new/borg/repo + +**Import from rsync-time-backup**:: + + # Requires a prefix for archive naming + borg-import rsync_tmbackup --prefix=mybackup- /path/to/rsync/backups /path/to/new/borg/repo + +**Import from another Borg repository**:: + + # Useful for rebuilding or migrating Borg repositories + borg-import borg /path/to/old/borg/repo /path/to/new/borg/repo + +Common Options +-------------- + +**Add prefix to archive names**:: + + borg-import rsnapshot --prefix=imported- /source /destination + +**Pass additional options to borg create**:: + + borg-import rsynchl -o="--compression lz4" /source /destination + +**Debug mode for troubleshooting**:: + + borg-import --debug rsnapshot /source /destination + +How It Works +------------ + +borg-import uses a smart approach to preserve Borg's file cache efficiency: + +1. **Temporary relocation**: Source directories are temporarily moved to a common name (``borg-import-dir``) +2. **Archive creation**: Borg creates archives from this temporary location +3. **Restoration**: Original directories are moved back to their original locations +4. **Timestamp preservation**: Original backup timestamps are preserved in Borg archives + +This process ensures that Borg's deduplication and file cache work optimally across imports. + +Safety Features +--------------- + +- **Non-destructive**: Original backup structures are preserved +- **Resume capability**: If interrupted, the process can be safely restarted +- **Duplicate detection**: Archives already present in the destination are automatically skipped +- **Journal tracking**: A ``.snapshot`` file tracks the current operation for recovery + +Getting Help +------------ + +For detailed help on any importer:: + + borg-import -h + +For example:: + + borg-import rsnapshot -h + borg-import borg -h + +Common Issues +------------- + +**"borg command not found"** + Install BorgBackup first. See the `installation guide `_. + +**"borg-import-dir exists. Cannot continue"** + A previous import was interrupted. Check the directory and ``.snapshot`` file to understand what happened, then manually clean up if safe to do so. + +**Permission errors** + Ensure you have read access to source backups and write access to the destination repository. + +**Out of space** + Some importers (especially ``borg``) require substantial temporary space. Ensure adequate free space in the working directory. + +Next Steps +---------- + +- Read the detailed documentation for your specific backup format +- Consider setting up automated backups with your new Borg repository +- Learn about Borg's powerful features like mounting, pruning, and compression options From 9eff6670f5f14c8de0aea230731b9a24fdcb3db9 Mon Sep 17 00:00:00 2001 From: Farivar Tabatabaei Date: Sat, 26 Jul 2025 09:54:27 +0330 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=94=A7=20fix(pytest):=20move=20pytest?= =?UTF-8?q?=20config=20to=20[tool.pytest.ini=5Foptions]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Switched from [tool.pytest] to [tool.pytest.ini_options] in pyproject.toml to align with pytest's expected configuration format and avoid schema errors. ⚠️ Although it may seem inconsistent with other tools, the pytest team has reserved [tool.pytest] for future use with a richer TOML-native configuration 📦. The [tool.pytest.ini_options] section serves as a compatibility bridge with the existing .ini-style configuration system 🔄. 📚 As per: https://docs.pytest.org/en/stable/reference/customize.html#pyproject-toml --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 855baa2..7c2a0d2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,7 +45,7 @@ where = ["src"] [tool.setuptools_scm] write_to = "src/borg_import/_version.py" -[tool.pytest] +[tool.pytest.ini_options] python_files = "testsuite/*.py" testpaths = ["src"]