From ff9ef08f65e04cfbcede42009cb24bba7b0fc46d Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Sun, 25 Aug 2024 23:52:33 +0200 Subject: [PATCH 1/2] doc/backup: link to exit code for scripting section --- doc/040_backup.rst | 7 ++++--- doc/075_scripting.rst | 2 ++ 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/040_backup.rst b/doc/040_backup.rst index b53ae8d09..4c9a44c74 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -778,11 +778,12 @@ environment variables and configuration files; see their respective manuals. Exit status codes ***************** -Restic returns one of the following exit status codes after the backup command is run: +Restic returns an exit status code 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) +* further exit codes are documented in :ref:`exit-codes`. 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 @@ -795,5 +796,5 @@ file read errors that occurred while running the backup. If there are errors of restic will still try to complete the backup run with all the other files, and create a snapshot that then contains all but the unreadable files. -One can use these exit status codes in scripts and other automation tools, to make them aware of -the outcome of the backup run. To manually inspect the exit code in e.g. Linux, run ``echo $?``. +For use of these exit status codes in scripts and other automation tools, see :ref:`exit-codes`. +To manually inspect the exit code in e.g. Linux, run ``echo $?``. diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 94749e6fb..c619ead7c 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -39,6 +39,8 @@ Note that restic will also return exit code ``1`` if a different error is encoun If there are no errors, restic will return a zero exit code and print the repository metadata. +.. _exit-codes: + Exit codes ********** From 354c2c38cc1aa47469eb77ffbdf639350b5440ab Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Sun, 25 Aug 2024 23:53:12 +0200 Subject: [PATCH 2/2] doc/backup: move exit status codes section up --- doc/040_backup.rst | 48 +++++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 4c9a44c74..696b235cc 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -686,6 +686,30 @@ created as it would only be written at the very (successful) end of the backup operation. Previous snapshots will still be there and will still work. +Exit status codes +***************** + +Restic returns an exit status code 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) +* further exit codes are documented in :ref:`exit-codes`. + +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 +password or command line argument is provided. When restic returns this exit status code, one +should not expect a snapshot to have been created. + +Source file read errors occur when restic fails to read one or more files or directories that +it was asked to back up, e.g. due to permission problems. Restic displays the number of source +file read errors that occurred while running the backup. If there are errors of this type, +restic will still try to complete the backup run with all the other files, and create a +snapshot that then contains all but the unreadable files. + +For use of these exit status codes in scripts and other automation tools, see :ref:`exit-codes`. +To manually inspect the exit code in e.g. Linux, run ``echo $?``. + Environment Variables ********************* @@ -774,27 +798,3 @@ See :ref:`caching` for the rules concerning cache locations when 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 -***************** - -Restic returns an exit status code 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) -* further exit codes are documented in :ref:`exit-codes`. - -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 -password or command line argument is provided. When restic returns this exit status code, one -should not expect a snapshot to have been created. - -Source file read errors occur when restic fails to read one or more files or directories that -it was asked to back up, e.g. due to permission problems. Restic displays the number of source -file read errors that occurred while running the backup. If there are errors of this type, -restic will still try to complete the backup run with all the other files, and create a -snapshot that then contains all but the unreadable files. - -For use of these exit status codes in scripts and other automation tools, see :ref:`exit-codes`. -To manually inspect the exit code in e.g. Linux, run ``echo $?``.