From dd38e2c2dfd60ee8d8ffc89472f6b22454d91682 Mon Sep 17 00:00:00 2001
From: Thomas Waldmann <tw@waldmann-edv.de>
Date: Fri, 6 Mar 2026 21:26:36 +0100
Subject: [PATCH] docs: archive specification, FAQ, fixes #9248, fixes #9053

---
 docs/faq.rst                                  |  8 ++++++
 .../general/archive-specification.rst.inc     | 25 +++++++++++++++++++
 docs/usage/usage_general.rst.inc              |  2 ++
 3 files changed, 35 insertions(+)
 create mode 100644 docs/usage/general/archive-specification.rst.inc

diff --git a/docs/faq.rst b/docs/faq.rst
index 507ad0ecb..086a300b0 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -619,6 +619,14 @@ Please disclose security issues responsibly.
 Common issues
 #############
 
+Command error: ... needed to match precisely one archive, but matched N.
+------------------------------------------------------------------------
+
+The command wanted one archive to work with. But the parameters you gave either
+didn't match anything or they matched multiple archives.
+
+See :ref:`archive_specification` about how to refer to an archive.
+
 /path/to/repo is not a valid repository. Check repo config.
 -----------------------------------------------------------
 
diff --git a/docs/usage/general/archive-specification.rst.inc b/docs/usage/general/archive-specification.rst.inc
new file mode 100644
index 000000000..2e136465b
--- /dev/null
+++ b/docs/usage/general/archive-specification.rst.inc
@@ -0,0 +1,25 @@
+.. _archive_specification:
+
+Specifying an archive
+~~~~~~~~~~~~~~~~~~~~~
+
+How to refer to an archive depends on whether you use archive series or not.
+
+**By ID:** if you use archive series, many or all archives will have the same name, thus
+you need to refer to a single archive by its archive ID (see ``borg repo-list``
+output)::
+
+    borg info aid:f7dea078
+
+The ``aid:`` prefix does a prefix match on the archive ID (the hex representation
+of the archive fingerprint). You only need to give enough hex digits to uniquely
+identify the archive. This is useful when archive names are ambiguous or when
+you want to refer to an archive by its immutable ID.
+
+**By name:** if you don't use archive series, but do it old-style by giving every archive
+a unique name, you can refer to an archive by its name::
+
+    borg info my-backup-202512312359
+
+For more details on archive matching patterns (including shell-style globs,
+regular expressions, and matching by user/host/tags), see :ref:`borg_match-archives`.
diff --git a/docs/usage/usage_general.rst.inc b/docs/usage/usage_general.rst.inc
index 9334f3d21..3cd396f05 100644
--- a/docs/usage/usage_general.rst.inc
+++ b/docs/usage/usage_general.rst.inc
@@ -4,6 +4,8 @@
 
 .. include:: general/repository-locations.rst.inc
 
+.. include:: general/archive-specification.rst.inc
+
 .. include:: general/logging.rst.inc
 
 .. include:: general/return-codes.rst.inc