borgbackup 2.0.0b10__tar.gz → 2.0.0b12__tar.gz

{borgbackup-2.0.0b10 → borgbackup-2.0.0b12}/CHANGES.rst

@@ -42,17 +42,23 @@ Compatibility notes:
   - ssh:// URLs: removed support for /~otheruser/, #6855.
     If you used this, just replace it by: ssh://user@host:port/home/otheruser/
   - -P / --prefix option was removed, please use the similar -a / --match-archives.
-  - the archive name is always given separately from the repository
+  - archive names don't need to be unique anymore. to the contrary:
+    it is now strongly recommended to use the identical name for borg create
+    within the same series of archives to make borg work more efficiently.
+    the name now identifies a series of archive, to identify a single archive
+    please use aid:<archive-hash-prefix>, e.g.: borg delete aid:d34db33f
+  - the archive id is always given separately from the repository
     (differently than with borg 1.x you must not give repo::archive).
-  - the archive name is either given as a positional parameter, like:
+  - the series name or archive id is either given as a positional parameter,
+    like:
 
-    - borg create myarchive2 /some/path
-    - borg diff myarchive1 myarchive2
+    - borg create documents ~/Documents
+    - borg diff aid:deadbeef aid:d34db33f
   - or, if the command makes sense for an arbitrary amount of archives, archives
     can be selected using a glob pattern, like:
 
-    - borg delete -a 'sh:myarchive*'
-    - borg recreate -a 'sh:myarchive*'
+    - borg delete -a 'sh:myarchive-2024-??-??'
+    - borg recreate -a 'sh:myarchive-2024-??-??'
   - some borg 1.x commands that supported working on a repo AND on an archive
     were split into 2 commands, some others were renamed:
 
@@ -66,15 +72,15 @@ Compatibility notes:
       - borg repo-space
     - borg 2 archive commands:
 
-      - borg create ARCHIVE ...
-      - borg list ARCHIVE
-      - borg extract ARCHIVE ...
-      - borg diff ARCH1 ARCH2
-      - borg rename OLDNAME NEWNAME
-      - borg info -a ARCH_GLOB
-      - borg delete -a ARCH_GLOB
-      - borg recreate -a ARCH_GLOB ...
-      - borg mount -a ARCH_GLOB mountpoint ...
+      - borg create NAME ...
+      - borg list ID
+      - borg extract ID ...
+      - borg diff ID1 ID2
+      - borg rename ID NEWNAME
+      - borg info ID
+      - borg delete ID
+      - borg recreate ID ...
+      - borg mount -a ID mountpoint ...
 
     For more details, please consult the docs or --help option output.
   - create/recreate/import-tar --timestamp: defaults to local timezone
@@ -98,8 +104,8 @@ Compatibility notes:
 
   So you might need to edit your scripts like e.g.::
 
-      borg 1.x: --glob-archives 'myserver-*'
-      borg 2.0: --match-archives 'sh:myserver-*'
+      borg 1.x: --glob-archives 'myserver-2024-*'
+      borg 2.0: --match-archives 'sh:myserver-2024-*'
 
 - use platformdirs 3.x.x instead of home-grown code. Due to that:
 
@@ -123,24 +129,115 @@ Compatibility notes:
 Change Log 2.x
 ==============
 
-Version 2.0.0b10 (2024-09-09)
+Version 2.0.0b12 (2024-10-03)
 -----------------------------
 
 Please note:
 
-This is a beta release, only for testing - do not use for production repos.
+Beta releases are only for testing on NEW repos - do not use for production.
 
 For upgrade and compatibility hints, please also read the section "Upgrade Notes"
 above.
 
-TL;DR: this is a huge change and the first very fundamental change in how borg
-works since ever:
+New features:
+
+- tag: new command to set, add, remove tags.
+- repo-list: add tags/hostname/username/comment to default format, reorder, adjust.
+
+  Idea: not putting these into the archive name, but keeping them separate.
+- repo-list --short: only print archive IDs (unique IDs, used for scripting).
+- implement --match-archives user:USERNAME host:HOSTNAME tags:TAG1,TAG2,...
+- allow -a / --match-archives multiple times (logical AND).
+
+  E.g.: borg delete -a home -a user:kenny -a host:kenny-pc
+- analyze: list changed chunks' sizes per directory.
+
+Fixes:
+
+- locking: also refresh the lock in other repo methods. avoid repo lock
+  getting stale when processing lots of unchanged files, #8442.
+- make sure the store gets closed in case of exceptions, #8413.
+- msgpack: increase max_buffer_size to ~4GiB, #8440.
+- Location.canonical_path: fix protocol and host display, #8446.
+
+Other changes:
+
+- give borgstore.Store a complete levels configuration, #8432.
+- add BORG_STORE_DATA_LEVELS=2 env var.
+- check: also display archive timestamp.
+- vagrant:
+
+  - use python 3.12.6 for binary builds.
+  - new testing box based on bento/ubuntu-24.04.
+  - install Rust on BSD.
+
+
+Version 2.0.0b11 (2024-09-26)
+-----------------------------
+
+New features:
 
-- you will need to create new repos.
-- likely more exciting than previous betas, definitely not for production.
-- remove "borg check --repair --archives-only" from your script in case you
-  added that for b9. "borg compact -v" now finds and deletes orphan chunks
-  and also outputs some new stats.
+- Support rclone:// URLs for borg repositories.
+
+  This enables 70+ cloud storage products, including Amazon S3, Backblaze B2,
+  Ceph, Dropbox, ftp(s), Google Cloud Storage, Google Drive, Microsoft Azure,
+  Microsoft OneDrive, OpenStack Swift, pCloud, Seafile, sftp, SMB / CIFS and
+  WebDAV!
+
+  See https://rclone.org/ for more details.
+- Parallel operations in same repo from same client (same user/machine).
+- Archive series feature, #7930.
+
+  TL;DR: a NAME now identifies a series of identically named archives,
+  to identify a specific single archive, use aid:<archive hash>.
+
+  in borg 1.x, we used to put a timestamp into the archive name, because borg1
+  required unique archive names.
+
+  borg2 does not require unique archive names, but it encourages you to even
+  use a identical archive names within the same SERIES of archives, e.g. you
+  could backup user files to archives named "user-files" and system files to
+  archives named "system-files".
+  that makes matching (e.g. for prune, for the files cache, ...) much simpler
+  and borg now KNOWS which archives belong to the same series (because they all
+  have the same name).
+- info/delete/prune: allow positional NAME argument, e.g.:
+
+  - borg prune --keep-daily 30 <seriesname>
+  - borg delete aid:<archive hash>
+- create: also archive inode number, #8362
+
+  Borg can use this when using archive series to rebuild the local files cache
+  from the previous archive (of the same series) in the repository.
+
+Fixes:
+
+- Remove superfluous repository.list() call. for high latency repos
+  (like sftp, cloud), this improves performance of borg check and compact.
+- repository.list: refresh lock more frequently
+- misc. commands fixed for non-unique archive names
+- remote: allow get_manifest method
+- files cache: fix rare race condition with data loss potential, #3536
+- storelocking: misc. fixes / cleanups
+
+Other changes:
+
+- Cache the chunks index in the repository, #8397.
+  Improves high latency repo performance for most commands compared to b10.
+- repo-compress: faster by using chunks index rather than repository.list().
+- Files cache entries now have both ctime AND mtime.
+- Borg updates the ctime and mtime of known and "unchanged" files, #4915.
+- Rebuild files cache from previous archive in same series, #8385.
+- Reduce RAM usage by splitting the files cache by archive series, #5658.
+- Remove AdHocCache, remove BORG_CACHE_IMPL (we only have one implementation).
+- Docs: user@ and :port are optional in sftp and ssh URLs.
+- CI: re-enable windows build after fixing it.
+- Upgrade pyinstaller to 6.10.0.
+- Increase IDS_PER_CHUNK, #6945.
+
+
+Version 2.0.0b10 (2024-09-09)
+-----------------------------
 
 New features:
 

{borgbackup-2.0.0b10 → borgbackup-2.0.0b12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: borgbackup
-Version: 2.0.0b10
+Version: 2.0.0b12
 Summary: Deduplicated, encrypted, authenticated and compressed backups
 Author: The Borg Collective (see AUTHORS file)
 Maintainer-email: Thomas Waldmann <tw@waldmann-edv.de>
@@ -32,7 +32,7 @@ Classifier: Topic :: System :: Archiving :: Backup
 Requires-Python: >=3.9
 License-File: LICENSE
 License-File: AUTHORS
-Requires-Dist: borgstore~=0.0.1
+Requires-Dist: borgstore~=0.0.4
 Requires-Dist: msgpack<=1.1.0,>=1.0.3
 Requires-Dist: packaging
 Requires-Dist: platformdirs<5.0.0,>=3.0.0; sys_platform == "darwin"

{borgbackup-2.0.0b10 → borgbackup-2.0.0b12}/docs/changes.rst

@@ -42,17 +42,23 @@ Compatibility notes:
   - ssh:// URLs: removed support for /~otheruser/, #6855.
     If you used this, just replace it by: ssh://user@host:port/home/otheruser/
   - -P / --prefix option was removed, please use the similar -a / --match-archives.
-  - the archive name is always given separately from the repository
+  - archive names don't need to be unique anymore. to the contrary:
+    it is now strongly recommended to use the identical name for borg create
+    within the same series of archives to make borg work more efficiently.
+    the name now identifies a series of archive, to identify a single archive
+    please use aid:<archive-hash-prefix>, e.g.: borg delete aid:d34db33f
+  - the archive id is always given separately from the repository
     (differently than with borg 1.x you must not give repo::archive).
-  - the archive name is either given as a positional parameter, like:
+  - the series name or archive id is either given as a positional parameter,
+    like:
 
-    - borg create myarchive2 /some/path
-    - borg diff myarchive1 myarchive2
+    - borg create documents ~/Documents
+    - borg diff aid:deadbeef aid:d34db33f
   - or, if the command makes sense for an arbitrary amount of archives, archives
     can be selected using a glob pattern, like:
 
-    - borg delete -a 'sh:myarchive*'
-    - borg recreate -a 'sh:myarchive*'
+    - borg delete -a 'sh:myarchive-2024-??-??'
+    - borg recreate -a 'sh:myarchive-2024-??-??'
   - some borg 1.x commands that supported working on a repo AND on an archive
     were split into 2 commands, some others were renamed:
 
@@ -66,15 +72,15 @@ Compatibility notes:
       - borg repo-space
     - borg 2 archive commands:
 
-      - borg create ARCHIVE ...
-      - borg list ARCHIVE
-      - borg extract ARCHIVE ...
-      - borg diff ARCH1 ARCH2
-      - borg rename OLDNAME NEWNAME
-      - borg info -a ARCH_GLOB
-      - borg delete -a ARCH_GLOB
-      - borg recreate -a ARCH_GLOB ...
-      - borg mount -a ARCH_GLOB mountpoint ...
+      - borg create NAME ...
+      - borg list ID
+      - borg extract ID ...
+      - borg diff ID1 ID2
+      - borg rename ID NEWNAME
+      - borg info ID
+      - borg delete ID
+      - borg recreate ID ...
+      - borg mount -a ID mountpoint ...
 
     For more details, please consult the docs or --help option output.
   - create/recreate/import-tar --timestamp: defaults to local timezone
@@ -98,8 +104,8 @@ Compatibility notes:
 
   So you might need to edit your scripts like e.g.::
 
-      borg 1.x: --glob-archives 'myserver-*'
-      borg 2.0: --match-archives 'sh:myserver-*'
+      borg 1.x: --glob-archives 'myserver-2024-*'
+      borg 2.0: --match-archives 'sh:myserver-2024-*'
 
 - use platformdirs 3.x.x instead of home-grown code. Due to that:
 
@@ -123,24 +129,115 @@ Compatibility notes:
 Change Log 2.x
 ==============
 
-Version 2.0.0b10 (2024-09-09)
+Version 2.0.0b12 (2024-10-03)
 -----------------------------
 
 Please note:
 
-This is a beta release, only for testing - do not use for production repos.
+Beta releases are only for testing on NEW repos - do not use for production.
 
 For upgrade and compatibility hints, please also read the section "Upgrade Notes"
 above.
 
-TL;DR: this is a huge change and the first very fundamental change in how borg
-works since ever:
+New features:
+
+- tag: new command to set, add, remove tags.
+- repo-list: add tags/hostname/username/comment to default format, reorder, adjust.
+
+  Idea: not putting these into the archive name, but keeping them separate.
+- repo-list --short: only print archive IDs (unique IDs, used for scripting).
+- implement --match-archives user:USERNAME host:HOSTNAME tags:TAG1,TAG2,...
+- allow -a / --match-archives multiple times (logical AND).
+
+  E.g.: borg delete -a home -a user:kenny -a host:kenny-pc
+- analyze: list changed chunks' sizes per directory.
+
+Fixes:
+
+- locking: also refresh the lock in other repo methods. avoid repo lock
+  getting stale when processing lots of unchanged files, #8442.
+- make sure the store gets closed in case of exceptions, #8413.
+- msgpack: increase max_buffer_size to ~4GiB, #8440.
+- Location.canonical_path: fix protocol and host display, #8446.
+
+Other changes:
+
+- give borgstore.Store a complete levels configuration, #8432.
+- add BORG_STORE_DATA_LEVELS=2 env var.
+- check: also display archive timestamp.
+- vagrant:
+
+  - use python 3.12.6 for binary builds.
+  - new testing box based on bento/ubuntu-24.04.
+  - install Rust on BSD.
+
+
+Version 2.0.0b11 (2024-09-26)
+-----------------------------
+
+New features:
 
-- you will need to create new repos.
-- likely more exciting than previous betas, definitely not for production.
-- remove "borg check --repair --archives-only" from your script in case you
-  added that for b9. "borg compact -v" now finds and deletes orphan chunks
-  and also outputs some new stats.
+- Support rclone:// URLs for borg repositories.
+
+  This enables 70+ cloud storage products, including Amazon S3, Backblaze B2,
+  Ceph, Dropbox, ftp(s), Google Cloud Storage, Google Drive, Microsoft Azure,
+  Microsoft OneDrive, OpenStack Swift, pCloud, Seafile, sftp, SMB / CIFS and
+  WebDAV!
+
+  See https://rclone.org/ for more details.
+- Parallel operations in same repo from same client (same user/machine).
+- Archive series feature, #7930.
+
+  TL;DR: a NAME now identifies a series of identically named archives,
+  to identify a specific single archive, use aid:<archive hash>.
+
+  in borg 1.x, we used to put a timestamp into the archive name, because borg1
+  required unique archive names.
+
+  borg2 does not require unique archive names, but it encourages you to even
+  use a identical archive names within the same SERIES of archives, e.g. you
+  could backup user files to archives named "user-files" and system files to
+  archives named "system-files".
+  that makes matching (e.g. for prune, for the files cache, ...) much simpler
+  and borg now KNOWS which archives belong to the same series (because they all
+  have the same name).
+- info/delete/prune: allow positional NAME argument, e.g.:
+
+  - borg prune --keep-daily 30 <seriesname>
+  - borg delete aid:<archive hash>
+- create: also archive inode number, #8362
+
+  Borg can use this when using archive series to rebuild the local files cache
+  from the previous archive (of the same series) in the repository.
+
+Fixes:
+
+- Remove superfluous repository.list() call. for high latency repos
+  (like sftp, cloud), this improves performance of borg check and compact.
+- repository.list: refresh lock more frequently
+- misc. commands fixed for non-unique archive names
+- remote: allow get_manifest method
+- files cache: fix rare race condition with data loss potential, #3536
+- storelocking: misc. fixes / cleanups
+
+Other changes:
+
+- Cache the chunks index in the repository, #8397.
+  Improves high latency repo performance for most commands compared to b10.
+- repo-compress: faster by using chunks index rather than repository.list().
+- Files cache entries now have both ctime AND mtime.
+- Borg updates the ctime and mtime of known and "unchanged" files, #4915.
+- Rebuild files cache from previous archive in same series, #8385.
+- Reduce RAM usage by splitting the files cache by archive series, #5658.
+- Remove AdHocCache, remove BORG_CACHE_IMPL (we only have one implementation).
+- Docs: user@ and :port are optional in sftp and ssh URLs.
+- CI: re-enable windows build after fixing it.
+- Upgrade pyinstaller to 6.10.0.
+- Increase IDS_PER_CHUNK, #6945.
+
+
+Version 2.0.0b10 (2024-09-09)
+-----------------------------
 
 New features:
 

{borgbackup-2.0.0b10 → borgbackup-2.0.0b12}/docs/deployment/central-backup-server.rst

@@ -82,7 +82,7 @@ The options which are added to the key will perform the following:
 Due to the ``cd`` command we use, the server automatically changes the current
 working directory. Then client doesn't need to have knowledge of the absolute
 or relative remote repository path and can directly access the repositories at
-``<user>@<host>:<repo>``.
+``ssh://<user>@<host>/./<repo>``.
 
 .. note:: The setup above ignores all client given commandline parameters
           which are normally appended to the `borg serve` command.
@@ -94,21 +94,21 @@ The client needs to initialize the `pictures` repository like this:
 
 ::
 
- borg init backup@backup01.srv.local:pictures
+ borg init ssh://backup@backup01.srv.local/./pictures
 
 Or with the full path (should actually never be used, as only for demonstration purposes).
 The server should automatically change the current working directory to the `<client fqdn>` folder.
 
 ::
 
-  borg init backup@backup01.srv.local:/home/backup/repos/johndoe.clnt.local/pictures
+  borg init ssh://backup@backup01.srv.local/home/backup/repos/johndoe.clnt.local/pictures
 
 When `johndoe.clnt.local` tries to access a not restricted path the following error is raised.
 John Doe tries to back up into the Web 01 path:
 
 ::
 
-  borg init backup@backup01.srv.local:/home/backup/repos/web01.srv.local/pictures
+  borg init ssh://backup@backup01.srv.local/home/backup/repos/web01.srv.local/pictures
 
 ::
 

{borgbackup-2.0.0b10 → borgbackup-2.0.0b12}/docs/deployment/image-backup.rst

@@ -9,8 +9,8 @@ technique makes sure only the modified parts of the file are stored. Borg also h
 optional simple sparse file support for extract.
 
 It is of utmost importancy to pin down the disk you want to backup.
-You need to use the SERIAL for that. 
-Use: 
+You need to use the SERIAL for that.
+Use:
 
 .. code-block:: bash
 
@@ -26,10 +26,10 @@ Use:
     echo "Disk Identifier: $DISK_ID"
 
     # Use the following line to perform a borg backup for the full disk:
-    # borg create --read-special {now} "$DISK_ID"
+    # borg create --read-special disk-backup "$DISK_ID"
 
     # Use the following to perform a borg backup for all partitions of the disk
-    # borg create --read-special {now} "${PARTITIONS[@]}"
+    # borg create --read-special partitions-backup "${PARTITIONS[@]}"
 
     # Example output:
     # Partitions of /dev/nvme1n1:
@@ -37,8 +37,8 @@ Use:
     # /dev/nvme1n1p2
     # /dev/nvme1n1p3
     # Disk Identifier: /dev/nvme1n1
-    # borg create --read-special {now} /dev/nvme1n1
-    # borg create --read-special {now} /dev/nvme1n1p1 /dev/nvme1n1p2 /dev/nvme1n1p3
+    # borg create --read-special disk-backup /dev/nvme1n1
+    # borg create --read-special partitions-backup /dev/nvme1n1p1 /dev/nvme1n1p2 /dev/nvme1n1p3
 
 
 

{borgbackup-2.0.0b10 → borgbackup-2.0.0b12}/docs/faq.rst

@@ -147,7 +147,7 @@ Try using ``borg mount`` and ``rsync`` (or a similar tool that supports
 resuming a partial file copy from what's already copied).
 
 How can I switch append-only mode on and off?
------------------------------------------------------------------------------------------------------------------------------------
+---------------------------------------------
 
 You could do that (via borg config REPO append_only 0/1), but using different
 ssh keys and different entries in ``authorized_keys`` is much easier and also
@@ -318,16 +318,16 @@ How do I configure different prune policies for different directories?
 
 Say you want to prune ``/var/log`` faster than the rest of
 ``/``. How do we implement that? The answer is to back up to different
-archive *names* and then implement different prune policies for
-different prefixes. For example, you could have a script that does::
+archive *series* and then implement different prune policies for the
+different series. For example, you could have a script that does::
 
-    borg create --exclude var/log main-$(date +%Y-%m-%d) /
-    borg create logs-$(date +%Y-%m-%d) /var/log
+    borg create --exclude var/log main /
+    borg create logs /var/log
 
 Then you would have two different prune calls with different policies::
 
-    borg prune --verbose --list -d 30 -a 'sh:main-*'
-    borg prune --verbose --list -d 7  -a 'sh:logs-*'
+    borg prune --verbose --list -d 30 main
+    borg prune --verbose --list -d 7  logs
 
 This will keep 7 days of logs and 30 days of everything else.
 
@@ -357,6 +357,17 @@ to change them.
 
 Use ``borg repo-compress`` to efficiently recompress a complete repository.
 
+Why is backing up an unmodified FAT filesystem slow on Linux?
+-------------------------------------------------------------
+
+By default, the files cache used by BorgBackup considers the inode of files.
+When an inode number changes compared to the last backup, it hashes the file
+again. The ``vfat`` kernel driver does not produce stable inode numbers by
+default.  One way to achieve stable inode numbering is mounting the filesystem
+using ``nfs=nostale_ro``. Doing so implies mounting the filesystem read-only.
+Another option is to not consider inode numbers in the files cache by passing
+``--files-cache=ctime,size``.
+
 Security
 ########
 
@@ -837,50 +848,29 @@ already used.
 By default, ctime (change time) is used for the timestamps to have a rather
 safe change detection (see also the --files-cache option).
 
-Furthermore, pathnames recorded in files cache are always absolute, even if you
-specify source directories with relative pathname. If relative pathnames are
-stable, but absolute are not (for example if you mount a filesystem without
-stable mount points for each backup or if you are running the backup from a
-filesystem snapshot whose name is not stable), borg will assume that files are
-different and will report them as 'added', even though no new chunks will be
-actually recorded for them. To avoid this, you could bind mount your source
-directory in a directory with the stable path.
+Furthermore, pathnames used as key into the files cache are **as archived**,
+so make sure these are always the same (see ``borg list``).
 
 .. _always_chunking:
 
 It always chunks all my files, even unchanged ones!
 ---------------------------------------------------
 
-Borg maintains a files cache where it remembers the timestamp, size and
+Borg maintains a files cache where it remembers the timestamps, size and
 inode of files. When Borg does a new backup and starts processing a
 file, it first looks whether the file has changed (compared to the values
 stored in the files cache). If the values are the same, the file is assumed
 unchanged and thus its contents won't get chunked (again).
 
-Borg can't keep an infinite history of files of course, thus entries
-in the files cache have a "maximum time to live" which is set via the
-environment variable BORG_FILES_CACHE_TTL (and defaults to 20).
-Every time you do a backup (on the same machine, using the same user), the
-cache entries' ttl values of files that were not "seen" are incremented by 1
-and if they reach BORG_FILES_CACHE_TTL, the entry is removed from the cache.
-
-So, for example, if you do daily backups of 26 different data sets A, B,
-C, ..., Z on one machine (using the default TTL), the files from A will be
-already forgotten when you repeat the same backups on the next day and it
-will be slow because it would chunk all the files each time. If you set
-BORG_FILES_CACHE_TTL to at least 26 (or maybe even a small multiple of that),
-it would be much faster.
-
-Besides using a higher BORG_FILES_CACHE_TTL (which also increases memory usage),
-there is also BORG_FILES_CACHE_SUFFIX which can be used to have separate (smaller)
-files caches for each backup set instead of the default one (big) unified files cache.
-
-Another possible reason is that files don't always have the same path, for
-example if you mount a filesystem without stable mount points for each backup
-or if you are running the backup from a filesystem snapshot whose name is not
-stable. If the directory where you mount a filesystem is different every time,
-Borg assumes they are different files. This is true even if you back up these
-files with relative pathnames - borg uses full pathnames in files cache regardless.
+The files cache is stored separately (using a different filename suffix) per
+archive series, thus using always the same name for the archive is strongly
+recommended. The "rebuild files cache from previous archive in repo" feature
+also depends on that.
+Alternatively, there is also BORG_FILES_CACHE_SUFFIX which can be used to
+manually set a custom suffix (if you can't just use the same archive name).
+
+Another possible reason is that files don't always have the same path -
+borg uses the paths as seen in the archive when using ``borg list``.
 
 It is possible for some filesystems, such as ``mergerfs`` or network filesystems,
 to return inconsistent inode numbers across runs, causing borg to consider them changed.

{borgbackup-2.0.0b10 → borgbackup-2.0.0b12}/docs/installation.rst

@@ -350,7 +350,8 @@ Ensure to install the dependencies as described within :ref:`Dependencies: Windo
 
 ::
 
-    export SETUPTOOLS_USE_DISTUTILS=stdlib # Needed for pip to work - https://www.msys2.org/docs/python/#known-issues
+    # Needed for setuptools < 70.2.0 to work - https://www.msys2.org/docs/python/#known-issues
+    # export SETUPTOOLS_USE_DISTUTILS=stdlib
     pip install -e .
     pyinstaller -y scripts/borg.exe.spec
 

{borgbackup-2.0.0b10 → borgbackup-2.0.0b12}/docs/internals/data-structures.rst

@@ -474,18 +474,20 @@ guess what files you have based on a specific set of chunk sizes).
 The cache
 ---------
 
-The **files cache** is stored in ``cache/files`` and is used at backup time to
-quickly determine whether a given file is unchanged and we have all its chunks.
+The **files cache** is stored in ``cache/files.<SUFFIX>`` and is used at backup
+time to quickly determine whether a given file is unchanged and we have all its
+chunks.
 
 In memory, the files cache is a key -> value mapping (a Python *dict*) and contains:
 
-* key: id_hash of the encoded, absolute file path
+* key: id_hash of the encoded path (same path as seen in archive)
 * value:
 
+  - age (0 [newest], ..., BORG_FILES_CACHE_TTL - 1)
   - file inode number
   - file size
-  - file ctime_ns (or mtime_ns)
-  - age (0 [newest], 1, 2, 3, ..., BORG_FILES_CACHE_TTL - 1)
+  - file ctime_ns
+  - file mtime_ns
   - list of chunk (id, size) tuples representing the file's contents
 
 To determine whether a file has not changed, cached values are looked up via
@@ -514,7 +516,7 @@ be told to ignore the inode number in the check via --files-cache.
 The age value is used for cache management. If a file is "seen" in a backup
 run, its age is reset to 0, otherwise its age is incremented by one.
 If a file was not seen in BORG_FILES_CACHE_TTL backups, its cache entry is
-removed. See also: :ref:`always_chunking` and :ref:`a_status_oddity`
+removed.
 
 The files cache is a python dictionary, storing python objects, which
 generates a lot of overhead.