amorfo77/restic
1
0
Fork 0
mirror of https://github.com/restic/restic.git synced 2026-05-15 22:55:24 +00:00
Code Issues Projects Releases Wiki Activity

doc: update embedded help output and misc typos (#21804)

Browse Source
This commit is contained in:
Michael Eischer
2026-05-15 20:21:04 +02:00
committed by GitHub
parent 7acab7b1a9
commit 8abbc3703d
18 changed files with 171 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cmd/restic/cmd_generate.go
+1 -1
View File
@@ -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
===========
doc/010_introduction.rst
+1 -1
View File
@@ -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
doc/020_installation.rst
+17 -11
View File
@@ -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 <https://mise.jdx.dev>`__,
@@ -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 <https://restic.net/gpg-key-alex.asc>`__):
::
@@ -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:
doc/030_preparing_a_new_repo.rst
+8 -8
View File
@@ -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 <https://www.msys2.org/wiki/Porting/>`__ and
`here <https://github.com/rprichard/winpty>`__ for detail information).
`here <https://github.com/rprichard/winpty>`__ for detailed information).
On MSYS2, you can install ``winpty`` as follows:
.. code-block:: console
doc/040_backup.rst
+6 -6
View File
@@ -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 <https://bford.info/cachedir/>`__, 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 <https://bford.info/cachedir/>`__, 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.
doc/045_working_with_repos.rst
+8 -8
View File
@@ -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
doc/047_tuning_parameters.rst
+1 -1
View File
@@ -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
doc/050_restore.rst
+30 -29
View File
@@ -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 ``<snapshot>:<subfolder>``
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 ``<snapshot>:<subfolder>``, 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
doc/060_forget.rst
+8 -5
View File
@@ -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:
doc/075_scripting.rst
+11 -8
View File
@@ -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.
+---------------------------+----------------------------------------------------+-----------+
doc/077_troubleshooting.rst
+6 -4
View File
@@ -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 <https://forum.restic.net/>`_
.. _forum: https://forum.restic.net/
* `Forum <https://forum.restic.net/>`__
* 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
doc/080_examples.rst
+1 -1
View File
@@ -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
doc/090_participating.rst
+9 -9
View File
@@ -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 <subcommand>`` 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 <https://graphviz.org/>`__ 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 <https://restic.readthedocs.io/en/latest/design.html>`__.
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 <https://dave.cheney.net/2016/03/12/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/<sub-component>/<function>_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
doc/REST_backend.rst
+3 -3
View File
@@ -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
==================
doc/developer_information.rst
+2 -2
View File
@@ -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
doc/faq.rst
+2 -2
View File
@@ -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).
doc/manual_rest.rst
+54 -49
View File
@@ -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``
doc/view_repository.rst
+3 -3
View File
@@ -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 <ID>``.
The examples below are using part of the standard file structure for testing restic itself.