From 8abbc3703dd5b0783eda51a081675c157bc5f0ca Mon Sep 17 00:00:00 2001 From: Michael Eischer <9106997+MichaelEischer@users.noreply.github.com> Date: Fri, 15 May 2026 20:21:04 +0200 Subject: [PATCH] doc: update embedded help output and misc typos (#21804) --- cmd/restic/cmd_generate.go | 2 +- doc/010_introduction.rst | 2 +- doc/020_installation.rst | 28 +++++---- doc/030_preparing_a_new_repo.rst | 16 ++--- doc/040_backup.rst | 12 ++-- doc/045_working_with_repos.rst | 16 ++--- doc/047_tuning_parameters.rst | 2 +- doc/050_restore.rst | 59 +++++++++--------- doc/060_forget.rst | 13 ++-- doc/075_scripting.rst | 19 +++--- doc/077_troubleshooting.rst | 10 +-- doc/080_examples.rst | 2 +- doc/090_participating.rst | 18 +++--- doc/REST_backend.rst | 6 +- doc/developer_information.rst | 4 +- doc/faq.rst | 4 +- doc/manual_rest.rst | 103 ++++++++++++++++--------------- doc/view_repository.rst | 6 +- 18 files changed, 171 insertions(+), 151 deletions(-) diff --git a/cmd/restic/cmd_generate.go b/cmd/restic/cmd_generate.go index 6263804da..9f7d5611f 100644 --- a/cmd/restic/cmd_generate.go +++ b/cmd/restic/cmd_generate.go @@ -22,7 +22,7 @@ func newGenerateCommand(globalOptions *global.Options) *cobra.Command { Short: "Generate manual pages and auto-completion files (bash, fish, zsh, powershell)", Long: ` The "generate" command writes automatically generated files (like the man pages -and the auto-completion files for bash, fish and zsh). +and the auto-completion files for bash, fish, powershell and zsh). EXIT STATUS =========== diff --git a/doc/010_introduction.rst b/doc/010_introduction.rst index e6bffdea1..bdfc9b19e 100644 --- a/doc/010_introduction.rst +++ b/doc/010_introduction.rst @@ -46,7 +46,7 @@ You can list all the snapshots you created with: restic snapshots -You can restore a backup by noting the snapshot ID you want and running: +You can restore a snapshot by noting the snapshot ID you want and running: .. code-block:: console diff --git a/doc/020_installation.rst b/doc/020_installation.rst index 2f3582955..d14db5828 100644 --- a/doc/020_installation.rst +++ b/doc/020_installation.rst @@ -25,7 +25,7 @@ you can download and run without having to do additional installation work. Please see the :ref:`official_binaries` section below for various downloads. Official binaries can be updated in place by using the ``restic self-update`` -command. +command. The environment variable ``$GITHUB_ACCESS_TOKEN`` can be set to use a personal access token when updating. This increases the rate limit through authenticated GitHub API @@ -123,7 +123,7 @@ You can install it by adding this to your ``configuration.nix``: pkgs.restic ]; -Mise (Linux/MacOS/Windows) +Mise (Linux/macOS/Windows) ========================== If you are using `Mise `__, @@ -213,7 +213,7 @@ code available for download. Just download and run the one matching your system. On your first installation, if you desire, you can verify the integrity of your downloads by testing the SHA-256 checksums listed in ``SHA256SUMS`` and verifying -the integrity of the file ``SHA256SUMS`` with the PGP signature in ``SHA256SUMS.asc``. +the integrity of the file ``SHA256SUMS`` with the PGP signature in ``SHA256SUMS.asc``. The PGP signature was created using the key (`0x91A6868BD3F7A907 `__): :: @@ -351,18 +351,24 @@ Restic can write out man pages and bash/fish/zsh/powershell compatible autocompl $ ./restic generate --help The "generate" command writes automatically generated files (like the man pages - and the auto-completion files for bash, fish, zsh and powershell). + and the auto-completion files for bash, fish, powershell and zsh). + + EXIT STATUS + =========== + + Exit status is 0 if the command was successful. + Exit status is 1 if there was any error. Usage: - restic generate [flags] [command] + restic generate [flags] Flags: - --bash-completion file write bash completion file - --fish-completion file write fish completion file - -h, --help help for generate - --man directory write man pages to directory - --powershell-completion write powershell completion file - --zsh-completion file write zsh completion file + --bash-completion file write bash completion file (`-` for stdout) + --fish-completion file write fish completion file (`-` for stdout) + -h, --help help for generate + --man directory write man pages to directory + --powershell-completion file write powershell completion file (`-` for stdout) + --zsh-completion file write zsh completion file (`-` for stdout) Example for using sudo to write a bash completion script directly to the system-wide location: diff --git a/doc/030_preparing_a_new_repo.rst b/doc/030_preparing_a_new_repo.rst index 254deded9..0eb050c15 100644 --- a/doc/030_preparing_a_new_repo.rst +++ b/doc/030_preparing_a_new_repo.rst @@ -178,15 +178,15 @@ setting the arguments passed to the default SSH command (ignored when .. note:: Please be aware that SFTP servers close connections when no data is received by the client. This can happen when restic is processing huge - amounts of unchanged data. To avoid this issue add the following lines + amounts of unchanged data. To avoid this issue add the following lines to the client's .ssh/config file: :: ServerAliveInterval 60 ServerAliveCountMax 240 - - + + REST Server *********** @@ -457,7 +457,7 @@ Backblaze B2 Due to issues with error handling in the current B2 library that restic uses, the recommended way to utilize Backblaze B2 is by using its S3-compatible API. - + Follow the documentation to `generate S3-compatible access keys`_ and then setup restic as described at :ref:`Amazon S3`. This is expected to work better than using the Backblaze B2 backend directly. @@ -569,7 +569,7 @@ The number of concurrent connections to the Azure Blob Storage service can be se established. The access tier of the blobs uploaded to the Azure Blob Storage service can be set with the -``-o azure.access-tier=Cool`` switch. The allowed values are ``Hot``, ``Cool`` or ``Cold``. +``-o azure.access-tier=Cool`` switch. The allowed values are ``Hot``, ``Cool`` or ``Cold``. If unspecified, the default is inferred from the default configured on the storage account. Google Cloud Storage @@ -599,9 +599,9 @@ key file and the project ID as follows: $ export GOOGLE_PROJECT_ID=123123123123 $ export GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gs-secret-restic-key.json -Restic uses Google's client library to generate `default authentication material`_, +Restic uses Google's client library to generate `default authentication material`_, which means if you're running in Google Container Engine or are otherwise -located on an instance with default service accounts then these should work out of +located on an instance with default service accounts then these should work out of the box. Alternatively, you can specify an existing access token directly: @@ -774,7 +774,7 @@ interaction. If you use emulation environments like You can workaround this by using a special tool called ``winpty`` (look `here `__ and -`here `__ for detail information). +`here `__ for detailed information). On MSYS2, you can install ``winpty`` as follows: .. code-block:: console diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 3ccf5d39c..b0daaad9c 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -344,14 +344,14 @@ Excluding Files You can exclude folders and files by specifying exclude patterns, currently the exclude options are: -- ``--exclude`` Specified one or more times to exclude one or more items +- ``--exclude`` Specify one or more times to exclude one or more items - ``--iexclude`` Same as ``--exclude`` but ignores the case of paths -- ``--exclude-caches`` Specified once to exclude a folder's content if it contains `the special CACHEDIR.TAG file `__, but keep ``CACHEDIR.TAG``. -- ``--exclude-file`` Specified one or more times to exclude items listed in a given file +- ``--exclude-caches`` Specify once to exclude a folder's content if it contains `the special CACHEDIR.TAG file `__, but keep ``CACHEDIR.TAG``. +- ``--exclude-file`` Specify one or more times to exclude items listed in a given file - ``--iexclude-file`` Same as ``exclude-file`` but ignores cases like in ``--iexclude`` -- ``--exclude-if-present foo`` Specified one or more times to exclude a folder's content if it contains a file called ``foo`` (optionally having a given header, no wildcards for the file name supported) -- ``--exclude-larger-than size`` Specified once to exclude files larger than the given size -- ``--exclude-cloud-files`` Specified once to exclude online-only cloud files (such as OneDrive Files On-Demand, iCloud drive), currently only supported on Windows and macOS +- ``--exclude-if-present foo`` Specify one or more times to exclude a folder's content if it contains a file called ``foo`` (optionally having a given header, no wildcards for the file name supported) +- ``--exclude-larger-than size`` Specify once to exclude files larger than the given size +- ``--exclude-cloud-files`` Specify once to exclude online-only cloud files (such as OneDrive Files On-Demand, iCloud drive), currently only supported on Windows and macOS Please see ``restic help backup`` for more specific information about each exclude option. diff --git a/doc/045_working_with_repos.rst b/doc/045_working_with_repos.rst index 3fbfaff8a..a6742cf0e 100644 --- a/doc/045_working_with_repos.rst +++ b/doc/045_working_with_repos.rst @@ -95,7 +95,7 @@ To get a list of the files in a specific snapshot you can use the ``ls`` command $ restic ls 073a90db - snapshot 073a90db of [/home/user/work.txt] filtered by [] at 2024-01-21 16:51:18.474558607 +0100 CET): + snapshot 073a90db of [/home/user/work.txt] filtered by [] at 2024-01-21 16:51:18.474558607 +0100 CET: /home /home/user /home/user/work.txt @@ -107,7 +107,7 @@ The ``--host`` flag can be used in conjunction to select the latest snapshot ori $ restic ls --host kasimir latest - snapshot 073a90db of [/home/user/work.txt] filtered by [] at 2024-01-21 16:51:18.474558607 +0100 CET): + snapshot 073a90db of [/home/user/work.txt] filtered by [] at 2024-01-21 16:51:18.474558607 +0100 CET: /home /home/user /home/user/work.txt @@ -124,7 +124,7 @@ as separator. $ restic ls latest /home - snapshot 073a90db of [/home/user/work.txt] filtered by [/home] at 2024-01-21 16:51:18.474558607 +0100 CET): + snapshot 073a90db of [/home/user/work.txt] filtered by [/home] at 2024-01-21 16:51:18.474558607 +0100 CET: /home /home/user @@ -132,7 +132,7 @@ as separator. $ restic ls --recursive latest /home - snapshot 073a90db of [/home/user/work.txt] filtered by [/home] at 2024-01-21 16:51:18.474558607 +0100 CET): + snapshot 073a90db of [/home/user/work.txt] filtered by [/home] at 2024-01-21 16:51:18.474558607 +0100 CET: /home /home/user /home/user/work.txt @@ -145,7 +145,7 @@ file permissions, UID, GID, file size, modification time and file path. For scri $ restic ls --long latest - snapshot 073a90db of [/home/user/work.txt] filtered by [] at 2024-01-21 16:51:18.474558607 +0100 CET): + snapshot 073a90db of [/home/user/work.txt] filtered by [] at 2024-01-21 16:51:18.474558607 +0100 CET: drwxr-xr-x 0 0 0 2024-01-21 16:50:52 /home drwxr-xr-x 0 0 0 2024-01-21 16:51:03 /home/user -rw-r--r-- 0 0 18 2024-01-21 16:51:03 /home/user/work.txt @@ -369,8 +369,8 @@ modifying the repository. Instead restic will only print the actions it would perform. .. note:: The ``rewrite`` command verifies that it does not modify snapshots in - unexpected ways and fails with an ``cannot encode tree at "[...]" without loosing information`` - error otherwise. This can occur when rewriting a snapshot created by a newer + unexpected ways and otherwise fails with the error ``cannot encode tree at "[...]" without losing information``. + This can occur when rewriting a snapshot created by a newer version of restic or some third-party implementation. To convert a snapshot into the format expected by the ``rewrite`` command @@ -457,7 +457,7 @@ If the repository structure is intact, restic will show that ``no errors were fo .. code-block:: console - $ restic -r /src/restic-repo check + $ restic -r /srv/restic-repo check ... load indexes check all packs diff --git a/doc/047_tuning_parameters.rst b/doc/047_tuning_parameters.rst index 1cd6b9329..b15a70825 100644 --- a/doc/047_tuning_parameters.rst +++ b/doc/047_tuning_parameters.rst @@ -26,7 +26,7 @@ When you start a backup, restic will concurrently count the number of files and their total size, which is used to estimate how long it will take. This will cause some extra I/O, which can slow down backups of network file systems or FUSE mounts. To avoid this overhead at the cost of not seeing a progress -estimate, use the ``--no-scan`` option of the ``backup`` command which disables +estimate, use the ``--no-scan`` option of the ``backup`` command which disables this file scanning. Backend Connections diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 153992fa2..3c92fcc98 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -27,9 +27,9 @@ command to restore the contents of the latest snapshot to enter password for repository: restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore -Use the word ``latest`` to restore the last backup. You can also combine -``latest`` with the ``--host`` and ``--path`` filters to choose the last -backup for a specific host, path or both: +Use the word ``latest`` to restore the latest snapshot. You can also combine +``latest`` with the ``--host`` and ``--path`` filters to choose the latest +snapshot for a specific host, path or both: .. code-block:: console @@ -41,51 +41,52 @@ Note that the ``--path`` option is only used to select the snapshot to restore, restrict the restore to a subset of files in the snapshot. This means that here the files will be restored to ``/tmp/restore/home/art`` and ``/tmp/restore/home/documents``. -Use ``--exclude`` and ``--include`` to restrict the restore to a subset of -files in the snapshot. For example, to restore a single file: +Use either ``--exclude`` or ``--include`` to restrict the restore to a subset of +files in the snapshot (the two are mutually exclusive). For example, to restore a single file: .. code-block:: console - $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore --include /work/foo + $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore --include /home/user/work/foo enter password for repository: restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore -This will restore the file ``/work/foo`` to ``/tmp/restore/work/foo``. +This will restore the file to ``/tmp/restore/home/user/work/foo``. To only restore a specific subfolder, you can use the ``:`` syntax, where ``snapshot`` is the ID of a snapshot (or the string ``latest``) and ``subfolder`` is a path within the snapshot. Note that the subfolder syntax also affects options like ``--include`` and ``--exclude``, such that their arguments should be specified relative to ``subfolder`` (e.g. ``/foo`` instead -of ``/work/foo``). +of ``/home/user/work/foo``). .. code-block:: console - $ restic -r /srv/restic-repo restore 79766175:/work --target /tmp/restore --include /foo + $ restic -r /srv/restic-repo restore 79766175:/home/user/work --target /tmp/restore --include /foo enter password for repository: restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore -This will restore the file ``/work/foo`` at the path ``/tmp/restore/foo``. +This will restore the file ``/home/user/work/foo`` to ``/tmp/restore/foo``. You can use the command ``restic ls latest`` or ``restic find foo`` to find the -path to the file within the snapshot. This path you can then pass to -``--include`` in verbatim to only restore the single file or directory. +path to the file within the snapshot. Pass that path to ``--include`` verbatim +when restoring the full snapshot; with ``:``, use a path relative +to ``subfolder`` as in the example above. -There are case insensitive variants of ``--exclude`` and ``--include`` called +There are case-insensitive variants of ``--exclude`` and ``--include`` called ``--iexclude`` and ``--iinclude``. These options will behave the same way but ignore the casing of paths. There are also ``--include-file``, ``--exclude-file``, ``--iinclude-file`` and ``--iexclude-file`` flags that read the include and exclude patterns from a file. -Restoring symbolic links on windows is only possible when the user has -``SeCreateSymbolicLinkPrivilege`` privilege or is running as admin. This is a -restriction of windows not restic. +Restoring symbolic links on Windows is only possible when the user has the +``SeCreateSymbolicLinkPrivilege`` privilege or is running as administrator. This is a +restriction of Windows, not restic. -Restoring full security descriptors on Windows is only possible when the user has -``SeRestorePrivilege``, ``SeSecurityPrivilege`` and ``SeTakeOwnershipPrivilege`` -privilege or is running as admin. This is a restriction of Windows not restic. -If either of these conditions are not met, only the DACL will be restored. +Restoring full security descriptors on Windows is only possible when the user has the +``SeRestorePrivilege``, ``SeSecurityPrivilege`` and ``SeTakeOwnershipPrivilege`` +privileges or is running as administrator. This is a restriction of Windows, not restic. +If not all of these privileges are available, only the DACL is restored. By default, restic does not restore files as sparse. Use ``restore --sparse`` to enable the creation of sparse files if supported by the filesystem. Then restic @@ -100,7 +101,7 @@ Restoring extended file attributes By default, all extended attributes for files are restored. -Use only ``--exclude-xattr`` or ``--include-xattr`` to control which extended +Use either ``--exclude-xattr`` or ``--include-xattr`` (not both) to control which extended attributes are restored for files in the snapshot. For example, to restore user and security namespaced extended attributes for files: @@ -148,7 +149,7 @@ exist in the snapshot. When specifying ``--include`` or ``--exclude`` options, only files or directories matched by those options will be deleted. For example, the command -``restic -r /srv/restic-repo restore 79766175:/work --target /tmp/restore --include /foo --delete`` +``restic -r /srv/restic-repo restore 79766175:/home/user/work --target /tmp/restore --include /foo --delete`` would only delete files within ``/tmp/restore/foo``. When using ``--target / --delete`` then the ``restore`` command only works if either an ``--include`` @@ -168,7 +169,7 @@ restored files when specifying ``--verbose=2``. .. code-block:: console - $ restic restore --target /tmp/restore --dry-run --verbose=2 latest + $ restic -r /srv/restic-repo restore --target /tmp/restore --dry-run --verbose=2 latest unchanged /restic/internal/walker/walker.go with size 2.812 KiB updated /restic/internal/walker/walker_test.go with size 11.143 KiB @@ -209,7 +210,7 @@ On FreeBSD, you may need to install FUSE and load the kernel module (``kldload f Restic supports storage and preservation of hard links. However, since hard links exist in the scope of a filesystem by definition, restoring -hard links from a fuse mount should be done by a program that preserves +hard links from a FUSE mount should be done by a program that preserves hard links. A program that does so is ``rsync``, used with the option ``--hard-links``. @@ -235,7 +236,7 @@ snapshots in a repository: .. code-block:: console $ restic -r /srv/restic-repo snapshots - ID Date Host Tags Directory + ID Date Host Tags Paths ---------------------------------------------------------------------- 562bfc5e 2018-07-14 20:18:01 mopped /home/user/file1 bbacb625 2018-07-14 20:18:07 mopped /home/other/work @@ -254,15 +255,15 @@ case, you can pass restic the snapshot ID of the snapshot you like to restore: $ restic -r /srv/restic-repo dump 098db9d5 production.sql | mysql Or you can pass restic a path that should be used for selecting the latest -snapshot. The path must match the patch printed in the "Directory" column, +snapshot. The path must match a path printed in the "Paths" column, e.g.: .. code-block:: console $ restic -r /srv/restic-repo dump --path /production.sql latest production.sql | mysql -If a snapshot was backed up using relative paths, then the directory shown in the output -of ``snapshots`` may differ from the directory structure in the snapshot. +If a snapshot was backed up using relative paths, then the paths shown in the output +of ``snapshots`` may differ from the path layout inside the snapshot. See :ref:`absolute-and-relative-paths` for details. Use ``ls`` to determine the correct path: .. code-block:: console @@ -273,7 +274,7 @@ See :ref:`absolute-and-relative-paths` for details. Use ``ls`` to determine the /other/work It is also possible to ``dump`` the contents of a whole folder structure to -stdout. To retain the information about the files and folders Restic will +stdout. To retain the information about the files and folders restic will output the contents in the tar (default) or zip format: .. code-block:: console diff --git a/doc/060_forget.rst b/doc/060_forget.rst index 10253013d..711644d14 100644 --- a/doc/060_forget.rst +++ b/doc/060_forget.rst @@ -181,10 +181,13 @@ The ``forget`` command accepts the following policy options: snapshots, keep only the most recent one for each month. - ``--keep-yearly n`` for the last ``n`` years which have one or more snapshots, keep only the most recent one for each year. -- ``--keep-tag`` keep all snapshots which have all tags specified by - this option (can be specified multiple times). The ``forget`` command will - exit with an error if all snapshots in a snapshot group would be removed - as none of them have the specified tags. +- ``--keep-tag`` keep snapshots that match at least one *tag list*. Each use of + the option defines one list: tags separated by commas mean the snapshot must + have all of those tags (AND within the list). When ``--keep-tag`` is given + multiple times, the lists are combined with OR (the snapshot is kept if it + matches any list). The ``forget`` command will exit with an error if all + snapshots in a snapshot group would be removed as none of them satisfy the + tag policy. - ``--keep-within duration`` keep all snapshots having a timestamp within the specified duration of the latest snapshot, where ``duration`` is a number of years, months, days, and hours. E.g. ``2y5m7d3h`` will keep all @@ -345,7 +348,7 @@ regardless of how many backups exist in the second week: .. code-block:: console - $ restic forget --keep-daily 5 --dry-run + $ restic forget --keep-within-daily 7d --dry-run repository f00c6e2a opened successfully Applying Policy: keep daily snapshots within 7d keep 4 snapshots: diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index f0c225d84..0662709c8 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -54,7 +54,7 @@ environment variables, which are listed below. RESTIC_AWS_ASSUME_ROLE_ARN Amazon IAM Role ARN to assume using discovered credentials RESTIC_AWS_ASSUME_ROLE_SESSION_NAME Session Name to use with the role assumption RESTIC_AWS_ASSUME_ROLE_EXTERNAL_ID External ID to use with the role assumption - RESTIC_AWS_ASSUME_ROLE_POLICY Inline Amazion IAM session policy + RESTIC_AWS_ASSUME_ROLE_POLICY Inline Amazon IAM session policy RESTIC_AWS_ASSUME_ROLE_REGION Region to use for IAM calls for the role assumption (default: us-east-1) RESTIC_AWS_ASSUME_ROLE_STS_ENDPOINT URL to the STS endpoint (default is determined based on RESTIC_AWS_ASSUME_ROLE_REGION). You generally do not need to set this, advanced use only. @@ -69,6 +69,7 @@ environment variables, which are listed below. GOOGLE_PROJECT_ID Project ID for Google Cloud Storage GOOGLE_APPLICATION_CREDENTIALS Application Credentials for Google Cloud Storage (e.g. $HOME/.config/gs-secret-restic-key.json) + GOOGLE_ACCESS_TOKEN Bearer access token for Google Cloud Storage (alternative to default application credentials) OS_AUTH_URL Auth URL for keystone authentication OS_REGION_NAME Region name for keystone authentication @@ -150,7 +151,8 @@ a more specific description. +-----+----------------------------------------------------+ | 2 | Go runtime error | +-----+----------------------------------------------------+ -| 3 | ``backup`` command could not read some source data | +| 3 | ``backup`` could not read some source data, or | +| | ``forget`` could not remove one or more snapshots | +-----+----------------------------------------------------+ | 10 | Repository does not exist (since restic 0.17.0) | +-----+----------------------------------------------------+ @@ -158,7 +160,7 @@ a more specific description. +-----+----------------------------------------------------+ | 12 | Wrong password (since restic 0.17.1) | +-----+----------------------------------------------------+ -| 130 | Restic was interrupted using SIGINT or SIGSTOP | +| 130 | Command was cancelled (e.g. SIGINT or SIGTERM) | +-----+----------------------------------------------------+ .. _JSON output: @@ -359,9 +361,10 @@ check ----- The ``check`` command uses the JSON lines format with the following message types. +Error lines are JSON objects on stderr; when the command finishes, one JSON summary is printed on stdout. -Status -^^^^^^ +Summary +^^^^^^^ +--------------------------+------------------------------------------------------------------------------------------------+----------+ | ``message_type`` | Always "summary" | string | @@ -491,7 +494,7 @@ Match object +-----------------+----------------------------------------------+-------------+ | ``links`` | Number of hardlinks | uint64 | +-----------------+----------------------------------------------+-------------+ -| ``link_target`` | Target of a symlink | string | +| ``linktarget`` | Target of a symlink | string | +-----------------+----------------------------------------------+-------------+ | ``uid`` | ID of owner | uint32 | +-----------------+----------------------------------------------+-------------+ @@ -696,7 +699,7 @@ node +------------------+----------------------------+-------------+ | ``mtime`` | Node modification time | time.Time | +------------------+----------------------------+-------------+ -| ``ctime`` | Node creation time | time.Time | +| ``ctime`` | Node change time (ctime) | time.Time | +------------------+----------------------------+-------------+ | ``inode`` | Inode number of node | uint64 | +------------------+----------------------------+-------------+ @@ -826,7 +829,7 @@ The snapshots command returns a single JSON array with objects of the structure SnapshotSummary object -The contained statistics reflect the information at the point64 in time when the snapshot +The contained statistics reflect the information at the point in time when the snapshot was created. +---------------------------+----------------------------------------------------+-----------+ diff --git a/doc/077_troubleshooting.rst b/doc/077_troubleshooting.rst index fd19f121d..374752499 100644 --- a/doc/077_troubleshooting.rst +++ b/doc/077_troubleshooting.rst @@ -31,7 +31,9 @@ or you are unsure how to proceed, then ask for help. Please always include the check output discussed in the next section and what steps you've taken to repair the repository so far. -* `Forum `_ +.. _forum: https://forum.restic.net/ + +* `Forum `__ * Our IRC channel ``#restic`` on ``irc.libera.chat`` Make sure that you **use the latest available restic version**. It can contain @@ -79,12 +81,12 @@ somewhere. Please include the check output and additional information that might help locate the problem. If ``check`` detects damaged pack files, it will show instructions on how to repair -them using the ``repair pack`` command. Use that command instead of the "Repair the +them using the ``repair packs`` command. Use that command instead of the "Repair the index" section in this guide. If you are interested to check only specific snapshots, you can now use the standard snapshot filter method specifying ``--host``, ``--path``, ``--tag`` or -alternatively naming snapshot ID(s) explicitely. The selected subset of packfiles +alternatively naming snapshot ID(s) explicitly. The selected subset of packfiles will then be checked for consistency and read when either ``--read-data`` or ``--read-data-subset`` is given. @@ -118,7 +120,7 @@ whether your issue is already known and solved. Please take a look at the .. note:: - If the `check` command tells you to run `restic repair pack`, then use that + If the `check` command tells you to run `restic repair packs`, then use that command instead. It will repair the damaged pack files and also update the index. Restic relies on its index to contain correct information about what data is diff --git a/doc/080_examples.rst b/doc/080_examples.rst index 8966c0447..d57566739 100644 --- a/doc/080_examples.rst +++ b/doc/080_examples.rst @@ -45,7 +45,7 @@ and log in using your AWS account. You will be presented with the AWS homepage: .. image:: images/aws_s3/01_aws_start.png :alt: AWS Homepage -By using the "Services" button in the upper left corder, a menu of all services +By using the "Services" button in the upper left corner, a menu of all services provided by AWS can be opened: .. image:: images/aws_s3/02_aws_menu.png diff --git a/doc/090_participating.rst b/doc/090_participating.rst index c5d534c70..01810f88b 100644 --- a/doc/090_participating.rst +++ b/doc/090_participating.rst @@ -19,7 +19,7 @@ Debug Logs ********** Set the environment variable ``DEBUG_LOG`` to let restic write extensive debug -messages to the specified filed, e.g.: +messages to the specified file, e.g.: .. code-block:: console @@ -74,11 +74,11 @@ This will make the ``restic debug `` available which can be used to inspect internal data structures. In addition, this enables profiling flags such as ``--cpu-profile`` and -``--mem-profile`` which can help with investigation performance and memory usage +``--mem-profile`` which can help when investigating performance and memory usage issues. See ``restic help`` for more details and a few additional ``--...-profile`` flags. -Running Restic with profiling enabled generates a ``.pprof`` file such as +Running restic with profiling enabled generates a ``.pprof`` file such as ``cpu.pprof``. To view a profile in a web browser, first make sure that the ``dot`` command from `Graphviz `__ is in the PATH. Then, run ``go tool pprof -http : cpu.pprof``. @@ -99,7 +99,7 @@ A document describing the design of restic and the data structures stored on the back end is contained in `Design `__. If you'd like to start contributing to restic, but don't know exactly -what do to, have a look at this great article by Dave Cheney: +what to do, have a look at this great article by Dave Cheney: `Suggestions for contributing to an Open Source project `__. A few issues have been tagged with the label ``help wanted``, you can @@ -113,7 +113,7 @@ Writing tests In case you want or need to create tests for an enhancement or a new feature of restic, here is a brief description of how to write tests. -Tests are typically falling into two categories: functional tests (unit tests) and integration tests. +Tests typically fall into two categories: functional tests (unit tests) and integration tests. Functional tests will verify the correct workings of a function or a set of functions. See more on integration tests below. @@ -134,7 +134,7 @@ Functional tests The packages in ``internal/...`` often provide ``Test*(...)`` functions and structs or have a dedicated test package like ``internal/backend/test``. -A good starting points are also the `testing.go` files that exist in several places. +A good starting point is to look at the `testing.go` files that exist in several places. Functional tests are stored in the same directory as their function, e.g. ``internal//_test.go``. @@ -176,7 +176,7 @@ A lot of the base helpers are found in ``cmd/restic/integration_helpers_test.go` This is a typical setting for an integration test: -- run a ``backup``, compare number of files backup with the expected number of files +- run a ``backup``, compare number of files backed up with the expected number of files - run a ``backup``, run the ``ls`` command with a ``sort`` option and compare actual output with the expected output. For all backup related functions there is a directory tree which can be used for a @@ -186,8 +186,8 @@ symlinked files, an empty directory and a simple directory structure which is go Commands that require a ``progress.Printer`` should either be wrapped in ``withTermStatus`` or ``withCaptureStdout``. If you want to analyze JSON output, you use ``withCaptureStdout()``. -It returns the generated output in a ``*bytes.Buffer``. -JSON output can be unmarshalled to produce the approriate go structures; see +It returns the generated output in a ``*bytes.Buffer``. +JSON output can be unmarshalled to produce the appropriate go structures; see ``cmd/restic/cmd_find_integration_test.go`` as an example. Example: this is a typical setup for a backup / find scenario diff --git a/doc/REST_backend.rst b/doc/REST_backend.rst index 9e85187f9..b6b9b95c8 100644 --- a/doc/REST_backend.rst +++ b/doc/REST_backend.rst @@ -2,7 +2,7 @@ REST Backend ************ -Restic can interact with HTTP Backend that respects the following REST +Restic can interact with an HTTP backend that respects the following REST API. The following values are valid for ``{type}``: @@ -40,8 +40,8 @@ DELETE {path} Deletes the repository on the server side. The server responds with "200 OK" if the repository was successfully removed. If this function is not -implemented the server returns "501 Not Implemented", if this it is -denied by the server it returns "403 Forbidden". +implemented the server returns "501 Not Implemented", if this is denied +by the server it returns "403 Forbidden". HEAD {path}/config ================== diff --git a/doc/developer_information.rst b/doc/developer_information.rst index ce28317c6..26014362d 100644 --- a/doc/developer_information.rst +++ b/doc/developer_information.rst @@ -18,7 +18,7 @@ depends on the following things: * The path to the Go workspace (``GOPATH=/home/build/go``) * Other environment variables (mostly ``$GOOS``, ``$GOARCH``, ``$CGO_ENABLED``) -In addition, the compressed ZIP files for Windows depends on the modification +In addition, each compressed ZIP file for Windows depends on the modification timestamp and filename of the binary contained in it. In order to reproduce the exact same ZIP file every time, we update the timestamp of the file ``VERSION`` in the source code archive and set the timezone to Europe/Berlin. @@ -152,7 +152,7 @@ binaries. For example, for restic 0.16.2 the command would be The script requires bash, curl, docker (version >= 25.0), git, gpg, shasum and tar. -The script first downloads all release binaries, checks the SHASUM256 file and its +The script first downloads all release binaries, checks the ``SHA256SUMS`` file and its signature. Afterwards it checks that the tarball matches the restic git repository contents, before first reproducing the builder docker container and finally the restic binaries. As final step, the restic binary in both the docker hub images diff --git a/doc/faq.rst b/doc/faq.rst index 2dedb1033..f777d1309 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -168,7 +168,7 @@ Take a look at the `ionice manpage`_ to learn about the other classes. To change the **CPU scheduling priority** to a higher-than-standard -value, use would run: +value, you would run: :: @@ -182,7 +182,7 @@ You can also **combine IO and CPU scheduling priority**: :: -$ ionice -c2 nice -n19 ./restic -r /media/gour/backup/ backup /home +$ ionice -c2 nice -n19 ./restic -r /media/your/backup/ backup /home This example puts restic in the IO class 2 (best effort) and tells the CPU scheduling algorithm to give it the least favorable niceness (19). diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst index a5e3e4af9..39a6b6536 100644 --- a/doc/manual_rest.rst +++ b/doc/manual_rest.rst @@ -55,31 +55,32 @@ Usage help is available: version Print version information Flags: - --cacert file file to load root certificates from (default: use system certificates or $RESTIC_CACERT) - --cache-dir directory set the cache directory. (default: use system default cache directory) - --cleanup-cache auto remove old cache directories - --compression mode compression mode (only available for repository format version 2), one of (auto|off|max) (default: $RESTIC_COMPRESSION) (default auto) - -h, --help help for restic - --http-user-agent string set a http user agent for outgoing http requests - --insecure-no-password use an empty password for the repository, must be passed to every restic command (insecure) - --insecure-tls skip TLS certificate verification when connecting to the repository (insecure) - --json set output mode to JSON for commands that support it - --key-hint key key ID of key to try decrypting first (default: $RESTIC_KEY_HINT) - --limit-download rate limits downloads to a maximum rate in KiB/s. (default: unlimited) - --limit-upload rate limits uploads to a maximum rate in KiB/s. (default: unlimited) - --no-cache do not use a local cache - --no-extra-verify skip additional verification of data before upload (see documentation) - --no-lock do not lock the repository, this allows some operations on read-only repositories - -o, --option key=value set extended option (key=value, can be specified multiple times) - --pack-size size set target pack size in MiB, created pack files may be larger (default: $RESTIC_PACK_SIZE) - --password-command command shell command to obtain the repository password from (default: $RESTIC_PASSWORD_COMMAND) - -p, --password-file file file to read the repository password from (default: $RESTIC_PASSWORD_FILE) - -q, --quiet do not output comprehensive progress report - -r, --repo repository repository to backup to or restore from (default: $RESTIC_REPOSITORY) - --repository-file file file to read the repository location from (default: $RESTIC_REPOSITORY_FILE) - --retry-lock duration retry to lock the repository if it is already locked, takes a value like 5m or 2h (default: no retries) - --tls-client-cert file path to a file containing PEM encoded TLS client certificate and private key (default: $RESTIC_TLS_CLIENT_CERT) - -v, --verbose be verbose (specify multiple times or a level using --verbose=n, max level/times is 2) + --cacert file file to load root certificates from (default: use system certificates or $RESTIC_CACERT) + --cache-dir directory set the cache directory. (default: use system default cache directory) + --cleanup-cache auto remove old cache directories + --compression mode compression mode (only available for repository format version 2), one of (auto|off|fastest|better|max) (default: $RESTIC_COMPRESSION) (default auto) + -h, --help help for restic + --http-user-agent string set a http user agent for outgoing http requests + --insecure-no-password use an empty password for the repository, must be passed to every restic command (insecure) + --insecure-tls skip TLS certificate verification when connecting to the repository (insecure) + --json set output mode to JSON for commands that support it + --key-hint key key ID of key to try decrypting first (default: $RESTIC_KEY_HINT) + --limit-download rate limits downloads to a maximum rate in KiB/s. (default: unlimited) + --limit-upload rate limits uploads to a maximum rate in KiB/s. (default: unlimited) + --no-cache do not use a local cache + --no-extra-verify skip additional verification of data before upload (see documentation) + --no-lock do not lock the repository, this allows some operations on read-only repositories + -o, --option key=value set extended option (key=value, can be specified multiple times) + --pack-size size set target pack size in MiB, created pack files may be larger (default: $RESTIC_PACK_SIZE) + --password-command command shell command to obtain the repository password from (default: $RESTIC_PASSWORD_COMMAND) + -p, --password-file file file to read the repository password from (default: $RESTIC_PASSWORD_FILE) + -q, --quiet do not output comprehensive progress report + -r, --repo repository repository to backup to or restore from (default: $RESTIC_REPOSITORY) + --repository-file file file to read the repository location from (default: $RESTIC_REPOSITORY_FILE) + --retry-lock duration retry to lock the repository if it is already locked, takes a value like 5m or 2h (default: no retries) + --stuck-request-timeout duration duration after which to retry stuck requests (default 5m0s) + --tls-client-cert file path to a file containing PEM encoded TLS client certificate and private key (default: $RESTIC_TLS_CLIENT_CERT) + -v, --verbose be verbose (specify multiple times or a level using --verbose=n, max level/times is 2) Use "restic [command] --help" for more information about a command. @@ -102,6 +103,9 @@ command: Exit status is 0 if the command was successful. Exit status is 1 if there was a fatal error (no snapshot created). Exit status is 3 if some source data could not be read (incomplete snapshot created). + Exit status is 10 if the repository does not exist. + Exit status is 11 if the repository is already locked. + Exit status is 12 if the password is incorrect. Usage: restic backup [flags] [FILE/DIR] ... @@ -138,30 +142,31 @@ command: --with-atime store the atime for all files and directories Global Flags: - --cacert file file to load root certificates from (default: use system certificates or $RESTIC_CACERT) - --cache-dir directory set the cache directory. (default: use system default cache directory) - --cleanup-cache auto remove old cache directories - --compression mode compression mode (only available for repository format version 2), one of (auto|off|max) (default: $RESTIC_COMPRESSION) (default auto) - --http-user-agent string set a http user agent for outgoing http requests - --insecure-no-password use an empty password for the repository, must be passed to every restic command (insecure) - --insecure-tls skip TLS certificate verification when connecting to the repository (insecure) - --json set output mode to JSON for commands that support it - --key-hint key key ID of key to try decrypting first (default: $RESTIC_KEY_HINT) - --limit-download rate limits downloads to a maximum rate in KiB/s. (default: unlimited) - --limit-upload rate limits uploads to a maximum rate in KiB/s. (default: unlimited) - --no-cache do not use a local cache - --no-extra-verify skip additional verification of data before upload (see documentation) - --no-lock do not lock the repository, this allows some operations on read-only repositories - -o, --option key=value set extended option (key=value, can be specified multiple times) - --pack-size size set target pack size in MiB, created pack files may be larger (default: $RESTIC_PACK_SIZE) - --password-command command shell command to obtain the repository password from (default: $RESTIC_PASSWORD_COMMAND) - -p, --password-file file file to read the repository password from (default: $RESTIC_PASSWORD_FILE) - -q, --quiet do not output comprehensive progress report - -r, --repo repository repository to backup to or restore from (default: $RESTIC_REPOSITORY) - --repository-file file file to read the repository location from (default: $RESTIC_REPOSITORY_FILE) - --retry-lock duration retry to lock the repository if it is already locked, takes a value like 5m or 2h (default: no retries) - --tls-client-cert file path to a file containing PEM encoded TLS client certificate and private key (default: $RESTIC_TLS_CLIENT_CERT) - -v, --verbose be verbose (specify multiple times or a level using --verbose=n, max level/times is 2) + --cacert file file to load root certificates from (default: use system certificates or $RESTIC_CACERT) + --cache-dir directory set the cache directory. (default: use system default cache directory) + --cleanup-cache auto remove old cache directories + --compression mode compression mode (only available for repository format version 2), one of (auto|off|fastest|better|max) (default: $RESTIC_COMPRESSION) (default auto) + --http-user-agent string set a http user agent for outgoing http requests + --insecure-no-password use an empty password for the repository, must be passed to every restic command (insecure) + --insecure-tls skip TLS certificate verification when connecting to the repository (insecure) + --json set output mode to JSON for commands that support it + --key-hint key key ID of key to try decrypting first (default: $RESTIC_KEY_HINT) + --limit-download rate limits downloads to a maximum rate in KiB/s. (default: unlimited) + --limit-upload rate limits uploads to a maximum rate in KiB/s. (default: unlimited) + --no-cache do not use a local cache + --no-extra-verify skip additional verification of data before upload (see documentation) + --no-lock do not lock the repository, this allows some operations on read-only repositories + -o, --option key=value set extended option (key=value, can be specified multiple times) + --pack-size size set target pack size in MiB, created pack files may be larger (default: $RESTIC_PACK_SIZE) + --password-command command shell command to obtain the repository password from (default: $RESTIC_PASSWORD_COMMAND) + -p, --password-file file file to read the repository password from (default: $RESTIC_PASSWORD_FILE) + -q, --quiet do not output comprehensive progress report + -r, --repo repository repository to backup to or restore from (default: $RESTIC_REPOSITORY) + --repository-file file file to read the repository location from (default: $RESTIC_REPOSITORY_FILE) + --retry-lock duration retry to lock the repository if it is already locked, takes a value like 5m or 2h (default: no retries) + --stuck-request-timeout duration duration after which to retry stuck requests (default 5m0s) + --tls-client-cert file path to a file containing PEM encoded TLS client certificate and private key (default: $RESTIC_TLS_CLIENT_CERT) + -v, --verbose be verbose (specify multiple times or a level using --verbose=n, max level/times is 2) Subcommands that support showing progress information such as ``backup``, ``restore``, ``check`` and ``prune`` will do so unless the quiet flag ``-q`` diff --git a/doc/view_repository.rst b/doc/view_repository.rst index 280446cd9..1ec752e34 100644 --- a/doc/view_repository.rst +++ b/doc/view_repository.rst @@ -20,7 +20,7 @@ to extract certain data from a repository. Listing different file types in the repository ============================================== -The ``restic list`` allows listing objects in the repository based on type. +The ``restic list`` command allows listing objects in the repository based on type. The allowed types are (in alphabetic order): - blobs @@ -38,8 +38,8 @@ The output for ``blobs`` contains one or more lines of output of the form is the ``sha256sum`` of the ``blob``. The output of the ``restic list 'type-plural'`` is most commonly used for the ``restic cat 'type' ID`` -command to study an ``type`` object with an ``ID`` in more detail. The only exception to -this singular/plural ``type`` is ``ìndex``, which is used in both commands ``restic list index`` and +command to study a ``type`` object with an ``ID`` in more detail. The only exception to +this singular/plural ``type`` is ``index``, which is used in both commands ``restic list index`` and ``restic cat index ``. The examples below are using part of the standard file structure for testing restic itself.