manual corrections/reverts

.github/PULL_REQUEST_TEMPLATE

@@ -3,6 +3,6 @@ Thank you for contributing code to Borg; your help is appreciated!
 Before you submit a pull request, please make sure it complies with the
 guidelines in our documentation:
 
-https://borgbackup.readthedocs.io/en/stable/development.html#contributions
+https://borgbackup.readthedocs.io/en/latest/development.html#contributions
 
 **Please remove the text above before submitting your pull request.**

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-# badge: https://github.com/borgbackup/borg/workflows/CI/badge.svg?branch=1.4-maint
+# badge: https://github.com/borgbackup/borg/workflows/CI/badge.svg?branch=master
 
 name: CI
 

docs/binaries/00_README.txt

@@ -9,7 +9,7 @@ Download the correct files
 --------------------------
 
 AMD64/x86_64 architecture
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 borg-linux-glibc241 Linux (built on Debian 13 "Trixie" with glibc 2.41)
 borg-linux-glibc236 Linux (built on Debian 12 "Bookworm" with glibc 2.36)

docs/faq.rst

@@ -49,7 +49,7 @@ locations), the recommended way to do that is like this:
 
 This will create distinct (different repository ID) but related repositories.
 Related means using the same chunker secret and the same id_key, thus producing
-the same chunks/the same chunk IDs if the input data is the same.
+the same chunks / the same chunk IDs if the input data is the same.
 
 The two independent borg create invocations mean there is no error propagation
 from repo1 to repo2 when done like that.
@@ -76,7 +76,7 @@ run into this by yourself by restoring an older copy of your repository.
 "attack": An attacker may have replaced your repo with an older copy, trying to
 trigger AES counter reuse and break your repo encryption.
 
-Borg users have also reported that file system (fs) issues (e.g., hardware issues or I/O errors causing
+Borg users have also reported that file system issues (e.g., hardware issues or I/O errors causing
 the file system to become read-only) can cause this warning, see :issue:`7853`.
 
 If you decide to ignore this and accept unsafe operation for this repository,

docs/misc/internals-picture.txt

@@ -1,5 +1,5 @@
 BorgBackup from 10,000 m
-=======================
+========================
 
 +--------+ +--------+     +--------+
 |archive0| |archive1| ... |archiveN|

docs/quickstart_example.rst.inc

@@ -44,7 +44,7 @@
 
     $ borg -r /path/to/repo extract aid:b80e24d2
 
-7. Delete the first archive (please note that this does **not** immediately free repository disk space)::
+7. Delete the first archive (please note that this does **not** free repository disk space)::
 
     $ borg -r /path/to/repo delete aid:b80e24d2
 

docs/usage/general.rst

@@ -5,8 +5,8 @@ Borg consists of a number of commands. Each command accepts
 a number of arguments and options and interprets various environment variables.
 The following sections will describe each command in detail.
 
-Commands, options, parameters, paths, and similar elements are shown in fixed-width.
-Option values are underlined. Borg has a few options that accept a fixed set
+Commands, options, parameters, paths, and similar elements are shown in ``fixed-width``.
+Option values are `underlined. Borg has a few options that accept a fixed set
 of values (e.g., ``--encryption`` of :ref:`borg_repo-create`).
 
 .. container:: experimental

docs/usage/general/date-time.rst.inc

@@ -14,5 +14,5 @@ Internally, we store and process date and time as UTC.
 
 Some options accept a TIMESPAN parameter, which can be given as a number of
 years (e.g. ``2y``), months (e.g. ``12m``), weeks (e.g. ``2w``),
-days (e.g. ``7d``), hours (e.g. ``8h``), minutes (e.g. ``30m``),
-or seconds (e.g. ``150s``).
+days (e.g. ``7d``), hours (e.g. ``8H``), minutes (e.g. ``30M``),
+or seconds (e.g. ``150S``).

docs/usage/general/repository-locations.rst.inc

@@ -10,5 +10,5 @@ Commands that work with an arbitrary number of archives usually accept ``-a ARCH
 
 Archive names must not contain the ``/`` (slash) character. For simplicity,
 also avoid spaces or other characters that have special meaning to the
-shell or in a filesystem (Borg mount uses the archive name as a directory
+shell or in a filesystem (``borg mount`` uses the archive name as a directory
 name).

docs/usage/general/resources.rst.inc

@@ -35,7 +35,7 @@ CPU server:
 CPU (only for client/server operation):
     When using Borg in a client/server way with an ssh-type repository, the SSH
     processes used for the transport layer will need some CPU on the client and
-    on the server due to the crypto they are doing—especially if you are pumping
+    on the server due to the crypto they are doing — especially if you are pumping
     large amounts of data.
 
 Memory (RAM) client:

src/borg/archiver/extract_cmd.py

@@ -171,13 +171,10 @@ class ExtractMixIn:
             "--numeric-ids", dest="numeric_ids", action="store_true", help="only use numeric user and group identifiers"
         )
         subparser.add_argument(
-            "--noflags",
-            dest="noflags",
-            action="store_true",
-            help="do not extract or set flags (e.g. NODUMP, IMMUTABLE)",
+            "--noflags", dest="noflags", action="store_true", help="do not extract/set flags (e.g. NODUMP, IMMUTABLE)"
         )
-        subparser.add_argument("--noacls", dest="noacls", action="store_true", help="do not extract or set ACLs")
-        subparser.add_argument("--noxattrs", dest="noxattrs", action="store_true", help="do not extract or set xattrs")
+        subparser.add_argument("--noacls", dest="noacls", action="store_true", help="do not extract/set ACLs")
+        subparser.add_argument("--noxattrs", dest="noxattrs", action="store_true", help="do not extract/set xattrs")
         subparser.add_argument(
             "--stdout", dest="stdout", action="store_true", help="write all extracted data to stdout"
         )

src/borg/archiver/prune_cmd.py

@@ -119,7 +119,7 @@ def prune_split(archives, rule, n, kept_because=None):
 class PruneMixIn:
     @with_repository(compatibility=(Manifest.Operation.DELETE,))
     def do_prune(self, args, repository, manifest):
-        """Prune repository archives according to specified rules."""
+        """Prune archives according to specified rules."""
         if not any(
             (
                 args.secondly,
@@ -280,7 +280,7 @@ class PruneMixIn:
             description=self.do_prune.__doc__,
             epilog=prune_epilog,
             formatter_class=argparse.RawDescriptionHelpFormatter,
-            help="prune repository archives",
+            help="prune archives",
         )
         subparser.set_defaults(func=self.do_prune)
         subparser.add_argument(

src/borg/archiver/repo_create_cmd.py

@@ -69,7 +69,7 @@ class RepoCreateMixIn:
         store faster.
 
         Encryption mode TL;DR
-        ++++++++++++++++++++
+        +++++++++++++++++++++
 
         The encryption mode can only be configured when creating a new repository - you can
         neither configure it on a per-archive basis nor change the mode of an existing repository.

src/borg/archiver/repo_delete_cmd.py

@@ -17,7 +17,7 @@ logger = create_logger()
 class RepoDeleteMixIn:
     @with_repository(exclusive=True, manifest=False)
     def do_repo_delete(self, args, repository):
-        """Deletes the repository."""
+        """Deletes a repository."""
         self.output_list = args.output_list
         dry_run = args.dry_run
         keep_security_info = args.keep_security_info
@@ -92,7 +92,7 @@ class RepoDeleteMixIn:
 
         repo_delete_epilog = process_epilog(
             """
-        This command deletes the complete repository.
+        This command deletes a complete repository.
 
         When you delete a complete repository, the security info and local cache for it
         (if any) are also deleted. Alternatively, you can delete just the local cache
@@ -109,7 +109,7 @@ class RepoDeleteMixIn:
             description=self.do_repo_delete.__doc__,
             epilog=repo_delete_epilog,
             formatter_class=argparse.RawDescriptionHelpFormatter,
-            help="delete the repository",
+            help="delete a repository",
         )
         subparser.set_defaults(func=self.do_repo_delete)
         subparser.add_argument(

src/borg/archiver/tar_cmds.py

@@ -9,7 +9,7 @@ import time
 from ..archive import Archive, TarfileObjectProcessors, ChunksProcessor
 from ..compress import CompressionSpec
 from ..constants import *  # NOQA
-from ..helpers import HardLinkManager
+from ..helpers import HardLinkManager, IncludePatternNeverMatchedWarning
 from ..helpers import ProgressIndicatorPercent
 from ..helpers import dash_open
 from ..helpers import msgpack
@@ -250,6 +250,9 @@ class TarMixIn:
         # This does not close the fileobj (tarstream) we passed to it -- a side effect of the | mode.
         tar.close()
 
+        for pattern in matcher.get_unmatched_include_patterns():
+            self.print_warning_instance(IncludePatternNeverMatchedWarning(pattern))
+
     @with_repository(cache=True, compatibility=(Manifest.Operation.WRITE,))
     def do_import_tar(self, args, repository, manifest, cache):
         """Create a backup archive from a tarball"""

src/borg/helpers/fs.py

@@ -126,7 +126,7 @@ def get_socket_filename():
 
 
 def get_cache_dir(*, legacy=False, create=True):
-    """Determine where to store Borg cache data"""
+    """Determine where to store Borg cache data."""
 
     if legacy:
         # Get cache home path
@@ -162,7 +162,7 @@ def get_cache_dir(*, legacy=False, create=True):
 
 
 def get_config_dir(*, legacy=False, create=True):
-    """Determine where to store the configuration"""
+    """Determine where to store the configuration."""
 
     # Get config home path
     if legacy:

src/borg/helpers/msgpack.py

@@ -1,8 +1,8 @@
 """
-Wrapping MessagePack
+Wrapping msgpack
 ================
 
-We wrap MessagePack here as needed to avoid clutter in the calling code.
+We wrap ``msgpack`` here as needed to avoid clutter in the calling code.
 
 Packing
 -------
@@ -32,17 +32,17 @@ Unpacking
 
 - unicode_errors = 'surrogateescape' -> see description above (will be used when raw is False).
 
-As of Borg 2.0, we have fixed most of the MessagePack str/bytes issues (#968).
+As of Borg 2.0, we have fixed most of the `msgpack`` str/bytes issues (#968).
 Borg still needs to read old repositories, archives, keys, etc., so we cannot yet fix it completely.
-From now on, Borg only writes new data according to the MessagePack 2.0 spec,
+From now on, Borg only writes new data according to the msgpack 2.0 spec,
 thus we can remove some legacy support in a later Borg release (some places are marked with "legacy").
 
-Current behavior in MessagePack terms
-----------------------------
+Current behavior in msgpack terms
+---------------------------------
 
-- pack with use_bin_type=True (according to the MessagePack 2.0 spec)
+- pack with use_bin_type=True (according to the msgpack 2.0 spec)
 - packs str -> raw and bytes -> bin
-- unpack with raw=False (according to the MessagePack 2.0 spec, using unicode_errors='surrogateescape')
+- unpack with raw=False (according to the msgpack 2.0 spec, using unicode_errors='surrogateescape')
 - unpacks bin to bytes and raw to str (thus we need to convert to desired type if we want bytes from "raw")
 """
 
@@ -69,11 +69,11 @@ UNICODE_ERRORS = "surrogateescape"
 
 
 class PackException(Exception):
-    """Exception during MessagePack packing."""
+    """Exception during msgpack packing."""
 
 
 class UnpackException(Exception):
-    """Exception during MessagePack unpacking."""
+    """Exception during msgpack unpacking."""
 
 
 class Packer(mp_Packer):

src/borg/helpers/parseformat.py

@@ -119,7 +119,7 @@ def decode_dict(d, keys, encoding="utf-8", errors="surrogateescape"):
 
 
 def positive_int_validator(value):
-    """Argparse type for positive integers."""
+    """argparse type for positive integers."""
     int_value = int(value)
     if int_value <= 0:
         raise argparse.ArgumentTypeError("A positive integer is required: %s" % value)

src/borg/legacyrepository.py

@@ -109,7 +109,7 @@ class LegacyRepository:
     dir/hints.X
 
     Filesystem interaction
-    -----------------------
+    ----------------------
 
     LoggedIO generally tries to rely on common behaviours across transactional file systems.
 

src/borg/logger.py

@@ -60,7 +60,7 @@ import time
 import warnings
 from pathlib import Path
 
-logging_debugging_path: Path | None = None  # if set, write borg.logger debugging log to that path/borg-*.log
+logging_debugging_path: Path | None = None  # if set, write borg.logger debugging log to that_path/borg-*.log
 
 configured = False
 borg_serve_log_queue: queue.SimpleQueue = queue.SimpleQueue()

src/borg/platform/linux.pyx

@@ -153,7 +153,7 @@ def set_flags(path, bsd_flags, fd=None):
 
 def get_flags(path, st, fd=None):
     if stat.S_ISBLK(st.st_mode) or stat.S_ISCHR(st.st_mode) or stat.S_ISLNK(st.st_mode):
-        # Avoid opening device files—trying to open non-present devices can be rather slow.
+        # Avoid opening device files — trying to open non-present devices can be rather slow.
         # Avoid opening symlinks; O_NOFOLLOW would make the open() fail anyway.
         return 0
     cdef int linux_flags

src/borg/repository.py

@@ -33,7 +33,7 @@ def repo_lister(repository, *, limit=None):
 
 
 class Repository:
-    """BorgStore-based key-value store."""
+    """borgstore-based key/value store."""
 
     class AlreadyExists(Error):
         """A repository already exists at {}."""
@@ -56,12 +56,12 @@ class Repository:
         exit_mcode = 14
 
     class InvalidRepository(Error):
-        """{} is not a valid repository. Check the repository configuration."""
+        """{} is not a valid repository. Check the repository config."""
 
         exit_mcode = 15
 
     class InvalidRepositoryConfig(Error):
-        """{} does not have a valid configuration. Check the repository configuration [{}]."""
+        """{} does not have a valid config. Check the repository config [{}]."""
 
         exit_mcode = 16
 

src/borg/storelocking.py

@@ -213,7 +213,7 @@ class Lock:
         locks = self._find_locks(only_mine=True)
         if not locks:
             if ignore_not_found:
-                logger.debug("LOCK-RELEASE: trying to release a lock, but none was found.")
+                logger.debug("LOCK-RELEASE: trying to release the lock, but none was found.")
                 return
             else:
                 raise NotLocked(str(self.store))
@@ -246,7 +246,7 @@ class Lock:
         self._delete_lock(old_locks[0]["key"], update_last_refresh=False)
 
     def refresh(self):
-        """Refreshes the lock—call this frequently, but not later than every <stale> seconds."""
+        """Refreshes the lock; call this frequently, but not later than every <stale> seconds."""
         now = datetime.datetime.now(datetime.timezone.utc)
         if self.last_refresh_dt is not None and now > self.last_refresh_dt + self.refresh_td:
             old_locks = self._find_locks(only_mine=True)

src/borg/testsuite/archive_test.py

@@ -247,7 +247,7 @@ def test_invalid_msgpacked_item(packed, item_keys_serialized):
     assert not valid_msgpacked_dict(packed, item_keys_serialized)
 
 
-# pytest-xdist requires the same order for the keys and dicts:
+# pytest-xdist always requires the same order for the keys and dicts:
 IK = sorted(list(ITEM_KEYS))
 
 

src/borg/testsuite/archiver/__init__.py

@@ -35,7 +35,7 @@ from ...xattr import get_all
 RK_ENCRYPTION = "--encryption=repokey-aes-ocb"
 KF_ENCRYPTION = "--encryption=keyfile-chacha20-poly1305"
 
-# This points to src/borg/archiver (small, with only a few files).
+# This points to the ``src/borg/archiver`` directory (small, with only a few files).
 src_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "archiver"))
 src_file = "archiver/__init__.py"  # relative path of one file in src_dir
 
@@ -108,7 +108,7 @@ def cmd_fixture(request):
     elif request.param == "binary":
         exe = "borg.exe"
     else:
-        raise ValueError("Parameter must be 'python' or 'binary'.")
+        raise ValueError("param must be 'python' or 'binary'.")
 
     def exec_fn(*args, **kw):
         return exec_cmd(*args, exe=exe, fork=True, **kw)

src/borg/testsuite/archiver/create_cmd_test.py

@@ -85,7 +85,7 @@ def test_basic_functionality(archivers, request):
     if are_hardlinks_supported():
         expected.append("input/hardlink")
     if not have_root:
-        # We could not create these device files without (fake) root.
+        # We could not create these device files without (fake)root.
         expected.remove("input/bdev")
         expected.remove("input/cdev")
     if has_lchflags:

src/borg/testsuite/archiver/disk_full_test.py

@@ -1,5 +1,5 @@
 """
-Test "disk full" is very slow and not recommended for daily test runs.
+test_disk_full is very slow and not recommended for daily test runs.
 For this test, an empty, writable 700 MB filesystem mounted on DF_MOUNT is required.
 For speed and other reasons, it is recommended that the underlying block device is
 in RAM, not a magnetic or flash disk.

src/borg/testsuite/compress_test.py

@@ -56,7 +56,7 @@ def test_autodetect_invalid(invalid_cdata):
 
 def test_zlib_legacy_compat():
     # For compatibility reasons, we do not add an extra header for zlib,
-    # nor do we expect one when decompressing or auto-detecting
+    # nor do we expect one when decompressing / auto-detecting.
     for level in range(10):
         c = get_compressor(name="zlib_legacy", level=level, legacy_mode=True)
         meta1, cdata1 = c.compress({}, DATA)

src/borg/testsuite/helpers/fs_test.py

@@ -237,7 +237,7 @@ def test_dash_open():
     assert dash_open("-", "wb") is sys.stdout.buffer
 
 
-@pytest.mark.skipif(not are_hardlinks_supported(), reason="hard links not supported")
+@pytest.mark.skipif(not are_hardlinks_supported(), reason="hardlinks not supported")
 def test_safe_unlink_is_safe(tmpdir):
     contents = b"Hello, world\n"
     victim = tmpdir / "victim"
@@ -250,7 +250,7 @@ def test_safe_unlink_is_safe(tmpdir):
     assert victim.read_binary() == contents
 
 
-@pytest.mark.skipif(not are_hardlinks_supported(), reason="hard links not supported")
+@pytest.mark.skipif(not are_hardlinks_supported(), reason="hardlinks not supported")
 def test_safe_unlink_is_safe_ENOSPC(tmpdir, monkeypatch):
     contents = b"Hello, world\n"
     victim = tmpdir / "victim"

src/borg/testsuite/helpers/time_test.py

@@ -11,26 +11,26 @@ def utcfromtimestamp(timestamp):
 
 def test_safe_timestamps():
     if SUPPORT_32BIT_PLATFORMS:
-        # Nanoseconds fit into int64.
+        # Nanoseconds fitting into int64.
         assert safe_ns(2**64) <= 2**63 - 1
         assert safe_ns(-1) == 0
-        # Seconds fit into int32.
+        # Seconds fitting into int32.
         assert safe_s(2**64) <= 2**31 - 1
         assert safe_s(-1) == 0
-        # datetime will not stumble over the Y10K problem.
+        # datetime will not stumble over its Y10K problem.
         beyond_y10k = 2**100
         with pytest.raises(OverflowError):
             utcfromtimestamp(beyond_y10k)
         assert utcfromtimestamp(safe_s(beyond_y10k)) > datetime(2038, 1, 1)
         assert utcfromtimestamp(safe_ns(beyond_y10k) / 1000000000) > datetime(2038, 1, 1)
     else:
-        # Nanoseconds fit into int64.
+        # Nanoseconds fitting into int64.
         assert safe_ns(2**64) <= 2**63 - 1
         assert safe_ns(-1) == 0
         # Seconds are limited so that their ns conversion fits into int64.
         assert safe_s(2**64) * 1000000000 <= 2**63 - 1
         assert safe_s(-1) == 0
-        # datetime will not stumble over the Y10K problem.
+        # datetime will not stumble over its Y10K problem.
         beyond_y10k = 2**100
         with pytest.raises(OverflowError):
             utcfromtimestamp(beyond_y10k)

src/borg/testsuite/legacyrepository_test.py

@@ -108,7 +108,7 @@ def add_keys(repository):
 def repo_dump(repository, label=None):
     label = label + ": " if label is not None else ""
     H_trans = {H(i): i for i in range(10)}
-    H_trans[None] = -1  # key is None appears in commits
+    H_trans[None] = -1  # key == None appears in commits
     tag_trans = {TAG_PUT2: "put2", TAG_PUT: "put", TAG_DELETE: "del", TAG_COMMIT: "comm"}
     for segment, fn in repository.io.segment_iterator():
         for tag, key, offset, size, _ in repository.io.iter_objects(segment):

src/borg/testsuite/version_test.py

@@ -6,11 +6,11 @@ from ..version import parse_version, format_version
 @pytest.mark.parametrize(
     "version_str, version_tuple",
     [
-        # Setuptools < 8.0 uses "-"
+        # setuptools < 8.0 uses "-"
         ("1.0.0a1.dev204-g8866961.d20170606", (1, 0, 0, -4, 1)),
         ("1.0.0a1.dev204-g8866961", (1, 0, 0, -4, 1)),
         ("1.0.0-d20170606", (1, 0, 0, -1)),
-        # Setuptools >= 8.0 uses "+"
+        # setuptools >= 8.0 uses "+"
         ("1.0.0a1.dev204+g8866961.d20170606", (1, 0, 0, -4, 1)),
         ("1.0.0a1.dev204+g8866961", (1, 0, 0, -4, 1)),
         ("1.0.0+d20170606", (1, 0, 0, -1)),