From 609f84e0953fa871029648a4e57545324689df48 Mon Sep 17 00:00:00 2001 From: adrian5 Date: Mon, 22 Jan 2024 21:12:12 +0100 Subject: [PATCH 1/2] docs: fix formatting --- doc/040_backup.rst | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/doc/040_backup.rst b/doc/040_backup.rst index d36986441..2e68527e2 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -173,7 +173,7 @@ attributes have to match for its contents to be presumed unchanged: * Modification timestamp (mtime). * Metadata change timestamp (ctime). * File size. - * Inode number (internal number used to reference a file in a filesystem). + * inode number (internal number used to reference a file in a filesystem). The reason for requiring both mtime and ctime to match is that Unix programs can freely change mtime (and some do). In such cases, a ctime change may be @@ -482,13 +482,12 @@ want to save the access time for files and directories, you can pass the ``--with-atime`` option to the ``backup`` command. Note that ``restic`` does not back up some metadata associated with files. Of -particular note are:: - - - file creation date on Unix platforms - - inode flags on Unix platforms - - file ownership and ACLs on Windows - - the "hidden" flag on Windows +particular note are: + * File creation date on Unix platforms + * inode flags on Unix platforms + * File ownership and ACLs on Windows + * The "hidden" flag on Windows Reading data from a command *************************** @@ -514,7 +513,6 @@ Restic uses the command exit code to determine whether the command succeeded. A non-zero exit code from the command causes restic to cancel the backup. This causes restic to fail with exit code 1. No snapshot will be created in this case. - Reading data from stdin *********************** @@ -555,7 +553,6 @@ the pipe and act accordingly (e.g., remove the last backup). Refer to the `Use the Unofficial Bash Strict Mode `__ for more details on this. - Tags for backup *************** @@ -684,7 +681,6 @@ The external programs that restic may execute include ``rclone`` (for rclone backends) and ``ssh`` (for the SFTP backend). These may respond to further environment variables and configuration files; see their respective manuals. - Exit status codes ***************** From 18806944f63b341756b98cca8aa2eab3b9952c45 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Tue, 23 Jan 2024 19:01:22 +0100 Subject: [PATCH 2/2] doc: remove blockquotes from unordered lists --- doc/030_preparing_a_new_repo.rst | 20 ++++++------- doc/040_backup.rst | 50 ++++++++++++++++---------------- doc/REST_backend.rst | 16 +++++----- doc/design.rst | 2 +- doc/developer_information.rst | 22 +++++++------- doc/manual_rest.rst | 8 ++--- 6 files changed, 59 insertions(+), 59 deletions(-) diff --git a/doc/030_preparing_a_new_repo.rst b/doc/030_preparing_a_new_repo.rst index 40215ad81..04fa45468 100644 --- a/doc/030_preparing_a_new_repo.rst +++ b/doc/030_preparing_a_new_repo.rst @@ -35,15 +35,15 @@ environment variable ``RESTIC_REPOSITORY_FILE``. For automating the supply of the repository password to restic, several options exist: - * Setting the environment variable ``RESTIC_PASSWORD`` +* Setting the environment variable ``RESTIC_PASSWORD`` - * Specifying the path to a file with the password via the option - ``--password-file`` or the environment variable ``RESTIC_PASSWORD_FILE`` +* Specifying the path to a file with the password via the option + ``--password-file`` or the environment variable ``RESTIC_PASSWORD_FILE`` + +* Configuring a program to be called when the password is needed via the + option ``--password-command`` or the environment variable + ``RESTIC_PASSWORD_COMMAND`` - * Configuring a program to be called when the password is needed via the - option ``--password-command`` or the environment variable - ``RESTIC_PASSWORD_COMMAND`` - The ``init`` command has an option called ``--repository-version`` which can be used to explicitly set the version of the new repository. By default, the current stable version is used (see table below). The alias ``latest`` will @@ -709,9 +709,9 @@ For debugging rclone, you can set the environment variable ``RCLONE_VERBOSE=2``. The rclone backend has three additional options: - * ``-o rclone.program`` specifies the path to rclone, the default value is just ``rclone`` - * ``-o rclone.args`` allows setting the arguments passed to rclone, by default this is ``serve restic --stdio --b2-hard-delete`` - * ``-o rclone.timeout`` specifies timeout for waiting on repository opening, the default value is ``1m`` +* ``-o rclone.program`` specifies the path to rclone, the default value is just ``rclone`` +* ``-o rclone.args`` allows setting the arguments passed to rclone, by default this is ``serve restic --stdio --b2-hard-delete`` +* ``-o rclone.timeout`` specifies timeout for waiting on repository opening, the default value is ``1m`` The reason for the ``--b2-hard-delete`` parameters can be found in the corresponding GitHub `issue #1657`_. diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 2e68527e2..ae834491e 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -170,10 +170,10 @@ On **Unix** (including Linux and Mac), given that a file lives at the same location as a file in a previous backup, the following file metadata attributes have to match for its contents to be presumed unchanged: - * Modification timestamp (mtime). - * Metadata change timestamp (ctime). - * File size. - * inode number (internal number used to reference a file in a filesystem). +* Modification timestamp (mtime). +* Metadata change timestamp (ctime). +* File size. +* Inode number (internal number used to reference a file in a filesystem). The reason for requiring both mtime and ctime to match is that Unix programs can freely change mtime (and some do). In such cases, a ctime change may be @@ -182,9 +182,9 @@ the only hint that a file did change. The following ``restic backup`` command line flags modify the change detection rules: - * ``--force``: turn off change detection and rescan all files. - * ``--ignore-ctime``: require mtime to match, but allow ctime to differ. - * ``--ignore-inode``: require mtime to match, but allow inode number +* ``--force``: turn off change detection and rescan all files. +* ``--ignore-ctime``: require mtime to match, but allow ctime to differ. +* ``--ignore-inode``: require mtime to match, but allow inode number and ctime to differ. The option ``--ignore-inode`` exists to support FUSE-based filesystems and @@ -250,9 +250,9 @@ It can be used like this: This instructs restic to exclude files matching the following criteria: - * All files matching ``*.c`` (parameter ``--exclude``) - * All files matching ``*.go`` (second line in ``excludes.txt``) - * All files and sub-directories named ``bar`` which reside somewhere below a directory called ``foo`` (fourth line in ``excludes.txt``) +* All files matching ``*.c`` (parameter ``--exclude``) +* All files matching ``*.go`` (second line in ``excludes.txt``) +* All files and sub-directories named ``bar`` which reside somewhere below a directory called ``foo`` (fourth line in ``excludes.txt``) Patterns use the syntax of the Go function `filepath.Match `__ @@ -270,8 +270,8 @@ environment variable (depending on your operating system). Patterns need to match on complete path components. For example, the pattern ``foo``: - * matches ``/dir1/foo/dir2/file`` and ``/dir/foo`` - * does not match ``/dir/foobar`` or ``barfoo`` +* matches ``/dir1/foo/dir2/file`` and ``/dir/foo`` +* does not match ``/dir/foobar`` or ``barfoo`` A trailing ``/`` is ignored, a leading ``/`` anchors the pattern at the root directory. This means, ``/bin`` matches ``/bin/bash`` but does not match ``/usr/bin/restic``. @@ -281,9 +281,9 @@ e.g. ``b*ash`` matches ``/bin/bash`` but does not match ``/bin/ash``. For this, the special wildcard ``**`` can be used to match arbitrary sub-directories: The pattern ``foo/**/bar`` matches: - * ``/dir1/foo/dir2/bar/file`` - * ``/foo/bar/file`` - * ``/tmp/foo/bar`` +* ``/dir1/foo/dir2/bar/file`` +* ``/foo/bar/file`` +* ``/tmp/foo/bar`` Spaces in patterns listed in an exclude file can be specified verbatim. That is, in order to exclude a file named ``foo bar star.txt``, put that just as it reads @@ -298,9 +298,9 @@ some escaping in order to pass the name/pattern as a single argument to restic. On most Unixy shells, you can either quote or use backslashes. For example: - * ``--exclude='foo bar star/foo.txt'`` - * ``--exclude="foo bar star/foo.txt"`` - * ``--exclude=foo\ bar\ star/foo.txt`` +* ``--exclude='foo bar star/foo.txt'`` +* ``--exclude="foo bar star/foo.txt"`` +* ``--exclude=foo\ bar\ star/foo.txt`` If a pattern starts with exclamation mark and matches a file that was previously matched by a regular pattern, the match is cancelled. @@ -484,10 +484,10 @@ want to save the access time for files and directories, you can pass the Note that ``restic`` does not back up some metadata associated with files. Of particular note are: - * File creation date on Unix platforms - * inode flags on Unix platforms - * File ownership and ACLs on Windows - * The "hidden" flag on Windows +* File creation date on Unix platforms +* Inode flags on Unix platforms +* File ownership and ACLs on Windows +* The "hidden" flag on Windows Reading data from a command *************************** @@ -686,9 +686,9 @@ Exit status codes Restic returns one of the following exit status codes after the backup command is run: - * 0 when the backup was successful (snapshot with all source files created) - * 1 when there was a fatal error (no snapshot created) - * 3 when some source files could not be read (incomplete snapshot with remaining files created) +* 0 when the backup was successful (snapshot with all source files created) +* 1 when there was a fatal error (no snapshot created) +* 3 when some source files could not be read (incomplete snapshot with remaining files created) Fatal errors occur for example when restic is unable to write to the backup destination, when there are network connectivity issues preventing successful communication, or when an invalid diff --git a/doc/REST_backend.rst b/doc/REST_backend.rst index f9d72cf06..9e85187f9 100644 --- a/doc/REST_backend.rst +++ b/doc/REST_backend.rst @@ -7,18 +7,18 @@ API. The following values are valid for ``{type}``: - * ``data`` - * ``keys`` - * ``locks`` - * ``snapshots`` - * ``index`` - * ``config`` +* ``data`` +* ``keys`` +* ``locks`` +* ``snapshots`` +* ``index`` +* ``config`` The API version is selected via the ``Accept`` HTTP header in the request. The following values are defined: - * ``application/vnd.x.restic.rest.v1`` or empty: Select API version 1 - * ``application/vnd.x.restic.rest.v2``: Select API version 2 +* ``application/vnd.x.restic.rest.v1`` or empty: Select API version 1 +* ``application/vnd.x.restic.rest.v2``: Select API version 2 The server will respond with the value of the highest version it supports in the ``Content-Type`` HTTP response header for the HTTP requests which should diff --git a/doc/design.rst b/doc/design.rst index 1e00a3358..b80029d10 100644 --- a/doc/design.rst +++ b/doc/design.rst @@ -824,4 +824,4 @@ Changes Repository Version 2 -------------------- - * Support compression for blobs (data/tree) and index / lock / snapshot files +* Support compression for blobs (data/tree) and index / lock / snapshot files diff --git a/doc/developer_information.rst b/doc/developer_information.rst index e7b60a03b..c7757e087 100644 --- a/doc/developer_information.rst +++ b/doc/developer_information.rst @@ -9,14 +9,14 @@ restic for version 0.10.0 and later. For restic versions down to 0.9.3 please refer to the documentation for the respective version. The binary produced depends on the following things: - * The source code for the release - * The exact version of the official `Go compiler `__ used to produce the binaries (running ``restic version`` will print this) - * The architecture and operating system the Go compiler runs on (Linux, ``amd64``) - * The build tags (for official binaries, it's the tag ``selfupdate``) - * The path where the source code is extracted to (``/restic``) - * The path to the Go compiler (``/usr/local/go``) - * The path to the Go workspace (``GOPATH=/home/build/go``) - * Other environment variables (mostly ``$GOOS``, ``$GOARCH``, ``$CGO_ENABLED``) +* The source code for the release +* The exact version of the official `Go compiler `__ used to produce the binaries (running ``restic version`` will print this) +* The architecture and operating system the Go compiler runs on (Linux, ``amd64``) +* The build tags (for official binaries, it's the tag ``selfupdate``) +* The path where the source code is extracted to (``/restic``) +* The path to the Go compiler (``/usr/local/go``) +* 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 timestamp and filename of the binary contained in it. In order to reproduce the @@ -69,9 +69,9 @@ container can be found in the `GitHub repository `__ The container serves the following goals: - * Have a very controlled environment which is independent from the local system - * Make it easy to have the correct version of the Go compiler at the right path - * Make it easy to pass in the source code to build at a well-defined path +* Have a very controlled environment which is independent from the local system +* Make it easy to have the correct version of the Go compiler at the right path +* Make it easy to pass in the source code to build at a well-defined path The following steps are necessary to build the binaries: diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst index d1c64ba6e..1ccd9268d 100644 --- a/doc/manual_rest.rst +++ b/doc/manual_rest.rst @@ -428,10 +428,10 @@ This allows faster operations, since meta data does not need to be loaded from a remote repository. The cache is automatically created, usually in an OS-specific cache folder: - * Linux/other: ``$XDG_CACHE_HOME/restic``, or ``~/.cache/restic`` if - ``XDG_CACHE_HOME`` is not set - * macOS: ``~/Library/Caches/restic`` - * Windows: ``%LOCALAPPDATA%/restic`` +* Linux/other: ``$XDG_CACHE_HOME/restic``, or ``~/.cache/restic`` if + ``XDG_CACHE_HOME`` is not set +* macOS: ``~/Library/Caches/restic`` +* Windows: ``%LOCALAPPDATA%/restic`` If the relevant environment variables are not set, restic exits with an error message.