borg/docs/usage
Thomas Waldmann 9ff9eb436f
windows: fix platformdirs directories, fixes #10237
borg called platformdirs with the appname only, so on Windows the
appauthor component defaulted to the appname and all default
directories ended up under a doubled AppData\...\borg\borg path.

Pass appauthor=False everywhere (no vendor directory level; on
Linux/macOS the appauthor is unused, so nothing changes there) and
roaming=True for the config dir, restoring the layout the CHANGES
upgrade notes had documented as intended all along:

- config (incl. keys): C:\Users\<user>\AppData\Roaming\borg
  (follows the user's roaming profile in domain environments)
- data (incl. security state): C:\Users\<user>\AppData\Local\borg
- cache: C:\Users\<user>\AppData\Local\borg\Cache
- runtime: C:\Users\<user>\AppData\Local\Temp\borg

This matches what comparable tools do on Windows (pip, rclone and
kopia keep the configuration in the roaming AppData and machine
state/caches in the local AppData, all without a vendor directory).
The cache keeps platformdirs' opinionated "Cache" subdir so the
CACHEDIR.TAG written into the cache root stays out of the data dir.

Only Windows is affected. The first Windows binary was only released
with 2.0.0b23, so beta users needing to migrate should be rare: move
the keys from the old %LOCALAPPDATA%\borg\borg\keys to the new
location (or set the BORG_* dir env vars to the old paths); cache and
security state are recreated as needed.

Docs: update the environment help topic (and the generated
environment.rst.inc), FAQ, key/transfer usage docs and CHANGES.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-30 19:16:22 +02:00
..
general windows: fix platformdirs directories, fixes #10237 2026-08-30 19:16:22 +02:00
analyze.rst analyze: sum up changed chunks per parent directory 2024-10-02 16:14:44 +02:00
analyze.rst.inc analyze: add --json output, fixes #9992 2026-08-01 22:56:48 +02:00
benchmark.rst docs: usage: add benchmark cpu and key change-location 2022-03-26 23:40:03 +01:00
benchmark_cpu.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
benchmark_crud.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
break-lock.rst.inc build_usage build_man 2025-12-23 18:00:09 +01:00
check.rst docs: split usage 2017-06-07 00:38:48 +02:00
check.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
common-options.rst.inc remove --debug-profile option, use BORG_DEBUG_PROFILE 2026-07-25 12:15:02 +02:00
compact.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
compact.rst.inc build_man / build_usage 2026-07-21 15:28:38 +02:00
completion.rst completion: borg can now generate completion scripts for supported shells, fixes #9172 2025-11-17 18:47:00 +01:00
completion.rst.inc completion: complete the --sort-by fields of list and diff 2026-08-12 15:59:40 +02:00
copy.rst docs: update repo-list output samples to the current default format 2026-08-29 15:04:30 +02:00
copy.rst.inc copy: new command to copy an archive to a new archive name, #2300 2026-08-28 06:30:19 +02:00
create.rst make fastcdc the default chunker, fixes #9957 2026-08-02 00:40:58 +02:00
create.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
debug.rst docs: fix name of the profile conversion command 2026-07-25 12:15:20 +02:00
delete.rst fixed typos and grammar (AI) 2025-09-23 14:56:23 +02:00
delete.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
diff.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
diff.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
export-tar.rst.inc export-tar: support sparse files, fixes #2562 2026-08-18 13:36:10 +02:00
extract.rst extract: document how to use wildcards in PATHs 2025-10-10 11:20:08 +02:00
extract.rst.inc build_man / build_usage 2026-07-21 15:28:38 +02:00
find.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
find.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
general.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
help.rst docs: split usage 2017-06-07 00:38:48 +02:00
help.rst.inc help topics: fix wrong claims, document missing env vars/placeholders 2026-08-28 14:46:51 +02:00
import-tar.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
info.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
info.rst.inc info: drop stale deduplicated-size note from epilog 2026-07-30 15:11:32 +02:00
key.rst windows: fix platformdirs directories, fixes #10237 2026-08-30 19:16:22 +02:00
key_add.rst.inc docs: add docs for "key add", "key list" and "key remove" 2026-06-13 21:37:21 +02:00
key_change-location.rst.inc build usage / man 2026-06-16 14:17:43 +02:00
key_change-passphrase.rst.inc build_usage / build_man / doc updates 2022-06-25 21:58:19 +02:00
key_export.rst.inc build usage / man 2026-06-16 14:17:43 +02:00
key_import.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
key_list.rst.inc docs: add docs for "key add", "key list" and "key remove" 2026-06-13 21:37:21 +02:00
key_remove.rst.inc docs: add docs for "key add", "key list" and "key remove" 2026-06-13 21:37:21 +02:00
list.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
list.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
lock.rst docs: split usage 2017-06-07 00:38:48 +02:00
mount.rst docs: update the mount -o versions example to the current naming 2026-08-28 23:26:15 +02:00
mount.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
notes.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
prune.rst Renames --since to --from 2026-06-20 18:36:59 +02:00
prune.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
recreate.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
recreate.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
rename.rst docs: update repo-list output samples to the current default format 2026-08-29 15:04:30 +02:00
rename.rst.inc build_usage build_man 2025-12-23 18:00:09 +01:00
repo-compress.rst re-add repo-compress, fixes #9663 2026-08-02 10:12:06 +02:00
repo-compress.rst.inc re-add repo-compress, fixes #9663 2026-08-02 10:12:06 +02:00
repo-create.rst docs: fix outdated --encryption mode names in examples 2026-08-26 14:43:18 +02:00
repo-create.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
repo-delete.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
repo-delete.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
repo-info.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
repo-info.rst.inc build_usage / build_man 2025-04-21 21:08:42 +02:00
repo-list.rst docs: update repo-list output samples to the current default format 2026-08-29 15:04:30 +02:00
repo-list.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
repo-space.rst docs: fix usage docs and references for repo-* commands 2024-09-08 18:06:26 +02:00
repo-space.rst.inc build_usage build_man 2026-03-15 14:37:50 +01:00
serve.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
serve.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
tag.rst tag: set, add, remove tags 2024-10-02 23:52:39 +02:00
tag.rst.inc build_usage build_man 2026-03-15 14:37:50 +01:00
tar.rst docs: fix broken examples and stale output samples in the usage docs 2026-08-28 12:48:17 +02:00
transfer.rst windows: fix platformdirs directories, fixes #10237 2026-08-30 19:16:22 +02:00
transfer.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
umount.rst.inc build_usage build_man 2025-12-23 18:00:09 +01:00
undelete.rst build_usage build_man 2024-11-16 20:14:16 +01:00
undelete.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
usage_general.rst.inc add support for yaml config files, default config 2026-03-10 18:36:30 +01:00
version.rst scripts/gendocs.py: make it work 2024-02-09 17:37:38 +01:00
version.rst.inc build_man ; build_usage 2026-08-29 17:42:35 +02:00
webdav.rst webdav: address review comments 2026-07-26 15:48:31 +02:00
webdav.rst.inc mount/webdav: BORG_MOUNT_ARCHIVE_DIR_FORMAT names the archive directories, fixes #9991 2026-08-21 17:31:42 +02:00
with-lock.rst.inc with-lock: fix epilog about leftover lock auto-removal, see #9870 2026-08-14 12:23:11 +02:00