📝 docs: add comprehensive quickstart guide #73

farivar-tabatabaei · 2025-07-26T06:23:14Z

📝 docs: Add comprehensive 🚀 quickstart guide for borg-import

Check commit 35dcf43 for the changes.

📌 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 it will automatically be included from "global.rst.inc" with ".. include:: global.rst.inc" directive.

This quickstart guide serves as a comprehensive introduction, getting users up and running quickly while explaining the underlying mechanics and safety features that make borg-import reliable.

🔧 fix(pytest): move pytest config to [tool.pytest.ini_options]

Check commit 9eff667 for the fix.

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

- 📌 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.

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

ThomasWaldmann

Thanks for your PR!

ThomasWaldmann · 2025-07-26T08:17:36Z

docs/quickstart.rst

+1. **BorgBackup installed**: borg-import requires the ``borg`` command to be available in your PATH.
+    Install it following the `BorgBackup installation guide <https://borgbackup.readthedocs.io/en/stable/installation.html>`_.
+
+2. **Python 3.9 or newer**: borg-import is written in Python and requires a modern Python version.


When we upgrade the python requirements, it would always need a change here also. Maybe this hint is not needed, I guess pip will also tell if the python requirement is not fulfilled.

I agree that pip will catch unmet Python version requirements. However, I think it's still helpful to keep line 17 as a quick upfront reminder for users reading the quickstart guide, especially those who might not be familiar with Python tooling. It provides a clearer picture of the prerequisites before they even try installing, which can help reduce friction and confusion and save time early on.

Also, the Python version requirement doesn’t change regularly, so the maintenance burden for this line should be minimal.

There isn't much "burden", but it can easily happen that this place is overlooked when raising the python requirements and then the docs will differ from the code reality until somebody notices.

ThomasWaldmann · 2025-07-26T08:18:41Z

docs/quickstart.rst

+
+Where:
+
+- ``<IMPORTER>`` is one of: ``borg``, ``rsnapshot``, ``rsynchl``, or ``rsync_tmbackup``


When we add a new importer, this would need fixing.

Does borg-import -h give a list of importers?

ThomasWaldmann · 2025-07-26T08:20:06Z

docs/quickstart.rst

+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.


"files cache"

(the cache file historically was named just "files")

ThomasWaldmann · 2025-07-26T08:22:17Z

docs/quickstart.rst

+Next Steps
+----------
+
+- Read the detailed documentation for your specific backup format


What do you mean? Read the borg docs?

The converter always converts to a borg repository.

ThomasWaldmann · 2025-07-26T08:24:48Z

docs/quickstart.rst

+
+- 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


Strictly taken, one would think about the desired compression before borg-import-ing into a borg repo and give the respective compression option to borg-import already. Preferably one does not want to use different compression algorithms for borg-import and later for borg.

ThomasWaldmann · 2025-07-26T08:26:42Z

docs/quickstart.rst

+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 <https://borgbackup.readthedocs.io/en/stable/installation.html>`_.


Strictly taken, the user has to use the version selector there and select precisely the version they are using.

ThomasWaldmann · 2025-07-26T08:28:06Z

docs/quickstart.rst

+    # Create a new Borg repository first
+    borg init --encryption=repokey /path/to/new/borg/repo
+    


Maybe move this to an own section.

ThomasWaldmann · 2025-07-26T08:28:16Z

docs/quickstart.rst

+    # Create a new Borg repository first
+    borg init --encryption=repokey /path/to/new/borg/repo
+    


ThomasWaldmann · 2025-07-26T08:31:20Z

docs/quickstart.rst

+
+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


Maybe avoid the word "restoration" here, considering it is usually used in a different meaning when talking about backing up and restoring files...

ThomasWaldmann · 2025-07-26T08:32:36Z

docs/quickstart.rst

+**"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.


Did you see that while using borg-import?

codecov · 2025-07-26T09:37:43Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 54.81%. Comparing base (935af3c) to head (9eff667).

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #73   +/-   ##
=======================================
  Coverage   54.81%   54.81%           
=======================================
  Files           9        9           
  Lines         332      332           
  Branches       46       46           
=======================================
  Hits          182      182           
  Misses        140      140           
  Partials       10       10

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

farivar-tabatabaei added 2 commits July 26, 2025 09:41

farivar-tabatabaei changed the title ~~📝 docs: Add comprehensive 🚀 quickstart guide for borg-import~~ 📝 docs: Add comprehensive 🚀 quickstart guide for borg-import -🔧 fix(pytest): move pytest config to [tool.pytest.ini_options] Jul 26, 2025

ThomasWaldmann reviewed Jul 26, 2025

View reviewed changes

ThomasWaldmann changed the title ~~📝 docs: Add comprehensive 🚀 quickstart guide for borg-import -🔧 fix(pytest): move pytest config to [tool.pytest.ini_options]~~ 📝 docs: add comprehensive quickstart guide Jul 26, 2025


		Where:

		- ``<IMPORTER>`` is one of: ``borg``, ``rsnapshot``, ``rsynchl``, or ``rsync_tmbackup``

		# Create a new Borg repository first
		borg init --encryption=repokey /path/to/new/borg/repo

		"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.

📝 docs: add comprehensive quickstart guide #73

Are you sure you want to change the base?

📝 docs: add comprehensive quickstart guide #73

Uh oh!

Conversation

farivar-tabatabaei commented Jul 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 docs: Add comprehensive 🚀 quickstart guide for borg-import

🔧 fix(pytest): move pytest config to [tool.pytest.ini_options]

Uh oh!

ThomasWaldmann left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

farivar-tabatabaei Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Jul 26, 2025

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

farivar-tabatabaei commented Jul 26, 2025 •

edited

Loading

farivar-tabatabaei Jul 27, 2025 •

edited

Loading