<commit_before>Manual
======

Usage help
----------

Usage help is available:

.. code-block:: console

    $ ./restic --help
    restic is a backup program which allows saving multiple revisions of files and
    directories in an encrypted repository stored on different backends.

    Usage:
      restic [command]

    Available Commands:
      autocomplete  Generate shell autocompletion script
      backup        Create a new backup of files and/or directories
      cat           Print internal objects to stdout
      check         Check the repository for errors
      dump          Dump data structures
      find          Find a file or directory
      forget        Remove snapshots from the repository
      help          Help about any command
      init          Initialize a new repository
      key           Manage keys (passwords)
      list          List items in the repository
      ls            List files in a snapshot
      mount         Mount the repository
      prune         Remove unneeded data from the repository
      rebuild-index Build a new index file
      restore       Extract the data from a snapshot
      snapshots     List all snapshots
      tag           Modify tags on snapshots
      unlock        Remove locks other processes created
      version       Print version information

    Flags:
          --json                   set output mode to JSON for commands that support it
          --no-lock                do not lock the repo, this allows some operations on read-only repos
      -p, --password-file string   read the repository password from a file
      -q, --quiet                  do not output comprehensive progress report
      -r, --repo string            repository to backup to or restore from (default: $RESTIC_REPOSITORY)

    Use "restic [command] --help" for more information about a command.

Similar to programs such as ``git``, restic has a number of
sub-commands. You can see these commands in the listing above. Each
sub-command may have own command-line options, and there is a help
option for each command which lists them, e.g. for the ``backup``
command:

.. code-block:: console

    $ ./restic backup --help
    The "backup" command creates a new snapshot and saves the files and directories
    given as the arguments.

    Usage:
      restic backup [flags] FILE/DIR [FILE/DIR] ...

    Flags:
      -e, --exclude pattern         exclude a pattern (can be specified multiple times)
          --exclude-file string     read exclude patterns from a file
          --files-from string       read the files to backup from file (can be combined with file args)
      -f, --force                   force re-reading the target files/directories. Overrides the "parent" flag
      -x, --one-file-system         Exclude other file systems
          --parent string           use this parent snapshot (default: last snapshot in the repo that has the same target files/directories)
          --stdin                   read backup from stdin
          --stdin-filename string   file name to use when reading from stdin
          --tag tag                 add a tag for the new snapshot (can be specified multiple times)
          --time string             time of the backup (ex. '2012-11-01 22:08:41') (default: now)

    Global Flags:
          --json                   set output mode to JSON for commands that support it
          --no-lock                do not lock the repo, this allows some operations on read-only repos
      -p, --password-file string   read the repository password from a file
      -q, --quiet                  do not output comprehensive progress report
      -r, --repo string            repository to backup to or restore from (default: $RESTIC_REPOSITORY)

Subcommand that support showing progress information such as ``backup``,
``check`` and ``prune`` will do so unless the quiet flag ``-q`` or
``--quiet`` is set. When running from a non-interactive console progress
reporting will be limited to once every 10 seconds to not fill your
logs.

Additionally on Unix systems if ``restic`` receives a SIGUSR signal the
current progress will written to the standard output so you can check up
on the status at will.

Initialize a repository
-----------------------

First, we need to create a "repository". This is the place where your
backups will be saved at.

Local
~~~~~

In order to create a repository at ``/tmp/backup``, run the following
command and enter the same password twice:

.. code-block:: console

    $ restic init --repo /tmp/backup
    enter password for new backend:
    enter password again:
    created restic backend 085b3c76b9 at /tmp/backup
    Please note that knowledge of your password is required to access the repository.
    Losing your password means that your data is irrecoverably lost.

Other backends like sftp and s3 are described in the following
sections.

Remembering your password is important! If you lose it, you won't be
able to access data stored in the repository.

For automated backups, restic accepts the repository location in the
environment variable ``RESTIC_REPOSITORY``. The password can be read
from a file (via the option ``--password-file``) or the environment
variable ``RESTIC_PASSWORD``.

SFTP
~~~~

In order to backup data via SFTP, you must first set up a server with
SSH and let it know your public key. Passwordless login is really
important since restic fails to connect to the repository if the server
prompts for credentials.

Once the server is configured, the setup of the SFTP repository can
simply be achieved by changing the URL scheme in the ``init`` command:

.. code-block:: console

    $ restic -r sftp:user@host:/tmp/backup init
    enter password for new backend:
    enter password again:
    created restic backend f1c6108821 at sftp:user@host:/tmp/backup
    Please note that knowledge of your password is required to access the repository.
    Losing your password means that your data is irrecoverably lost.

You can also specify a relative (read: no slash (``/``) character at the
beginning) directory, in this case the dir is relative to the remote
user's home directory.

The backend config string does not allow specifying a port. If you need
to contact an sftp server on a different port, you can create an entry
in the ``ssh`` file, usually located in your user's home directory at
``~/.ssh/config`` or in ``/etc/ssh/ssh_config``:
<commit_msg>manual: Add hint for RESTIC_PASSWORD_FILE<commit_after>Manual
======

Usage help
----------

Usage help is available:

.. code-block:: console

    $ ./restic --help
    restic is a backup program which allows saving multiple revisions of files and
    directories in an encrypted repository stored on different backends.

    Usage:
      restic [command]

    Available Commands:
      autocomplete  Generate shell autocompletion script
      backup        Create a new backup of files and/or directories
      cat           Print internal objects to stdout
      check         Check the repository for errors
      dump          Dump data structures
      find          Find a file or directory
      forget        Remove snapshots from the repository
      help          Help about any command
      init          Initialize a new repository
      key           Manage keys (passwords)
      list          List items in the repository
      ls            List files in a snapshot
      mount         Mount the repository
      prune         Remove unneeded data from the repository
      rebuild-index Build a new index file
      restore       Extract the data from a snapshot
      snapshots     List all snapshots
      tag           Modify tags on snapshots
      unlock        Remove locks other processes created
      version       Print version information

    Flags:
          --json                   set output mode to JSON for commands that support it
          --no-lock                do not lock the repo, this allows some operations on read-only repos
      -p, --password-file string   read the repository password from a file
      -q, --quiet                  do not output comprehensive progress report
      -r, --repo string            repository to backup to or restore from (default: $RESTIC_REPOSITORY)

    Use "restic [command] --help" for more information about a command.

Similar to programs such as ``git``, restic has a number of
sub-commands. You can see these commands in the listing above. Each
sub-command may have own command-line options, and there is a help
option for each command which lists them, e.g. for the ``backup``
command:

.. code-block:: console

    $ ./restic backup --help
    The "backup" command creates a new snapshot and saves the files and directories
    given as the arguments.

    Usage:
      restic backup [flags] FILE/DIR [FILE/DIR] ...

    Flags:
      -e, --exclude pattern         exclude a pattern (can be specified multiple times)
          --exclude-file string     read exclude patterns from a file
          --files-from string       read the files to backup from file (can be combined with file args)
      -f, --force                   force re-reading the target files/directories. Overrides the "parent" flag
      -x, --one-file-system         Exclude other file systems
          --parent string           use this parent snapshot (default: last snapshot in the repo that has the same target files/directories)
          --stdin                   read backup from stdin
          --stdin-filename string   file name to use when reading from stdin
          --tag tag                 add a tag for the new snapshot (can be specified multiple times)
          --time string             time of the backup (ex. '2012-11-01 22:08:41') (default: now)

    Global Flags:
          --json                   set output mode to JSON for commands that support it
          --no-lock                do not lock the repo, this allows some operations on read-only repos
      -p, --password-file string   read the repository password from a file
      -q, --quiet                  do not output comprehensive progress report
      -r, --repo string            repository to backup to or restore from (default: $RESTIC_REPOSITORY)

Subcommand that support showing progress information such as ``backup``,
``check`` and ``prune`` will do so unless the quiet flag ``-q`` or
``--quiet`` is set. When running from a non-interactive console progress
reporting will be limited to once every 10 seconds to not fill your
logs.

Additionally on Unix systems if ``restic`` receives a SIGUSR signal the
current progress will written to the standard output so you can check up
on the status at will.

Initialize a repository
-----------------------

First, we need to create a "repository". This is the place where your
backups will be saved at.

Local
~~~~~

In order to create a repository at ``/tmp/backup``, run the following
command and enter the same password twice:

.. code-block:: console

    $ restic init --repo /tmp/backup
    enter password for new backend:
    enter password again:
    created restic backend 085b3c76b9 at /tmp/backup
    Please note that knowledge of your password is required to access the repository.
    Losing your password means that your data is irrecoverably lost.

Other backends like sftp and s3 are described in the following
sections.

Remembering your password is important! If you lose it, you won't be
able to access data stored in the repository.

For automated backups, restic accepts the repository location in the
environment variable ``RESTIC_REPOSITORY``. The password can be read
from a file (via the option ``--password-file`` or the environment variable
``RESTIC_PASSWORD_FILE``) or the environment variable ``RESTIC_PASSWORD``.

SFTP
~~~~

In order to backup data via SFTP, you must first set up a server with
SSH and let it know your public key. Passwordless login is really
important since restic fails to connect to the repository if the server
prompts for credentials.

Once the server is configured, the setup of the SFTP repository can
simply be achieved by changing the URL scheme in the ``init`` command:

.. code-block:: console

    $ restic -r sftp:user@host:/tmp/backup init
    enter password for new backend:
    enter password again:
    created restic backend f1c6108821 at sftp:user@host:/tmp/backup
    Please note that knowledge of your password is required to access the repository.
    Losing your password means that your data is irrecoverably lost.

You can also specify a relative (read: no slash (``/``) character at the
beginning) directory, in this case the dir is relative to the remote
user's home directory.

The backend config string does not allow specifying a port. If you need
to contact an sftp server on a different port, you can create an entry
in the ``ssh`` file, usually located in your user's home directory at
``~/.ssh/config`` or in ``/etc/ssh/ssh_config``:

{'fraction_non_alphanumeric': 0.059350158215636335, 'fraction_numerical': 0.004939414988037355, 'mean_word_length': 2.485207100591716, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6222719', 'n_tokens_mistral': 3234, 'n_tokens_neox': 3082, 'n_words': 1713}