Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

dump requires absolute path from within the repo #4443

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

dump requires absolute path from within the repo #4443

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2c37fb2
dump requires absolute path from within the repo
marbx Aug 9, 2023
d57ef6e
Added path discrepancy to backup and listing
marbx Aug 16, 2023
1925457
Entered feedback from MichaelEischer
marbx Aug 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
11 changes: 11 additions & 0 deletions doc/040_backup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,17 @@ size of the files and directories in ``~/work`` on the local file system. It
also tells us that only 1.200 GiB was added to the repository. This means that
some of the data was duplicate and restic was able to efficiently reduce it.

We just attached the absolute path ``~/work`` to the backup, so the path
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to move this to it's own subsection, for example Paths in a snapshot and then show a backup using a relative and an absolute path each followed with the corresponding output of snapshots and ls as illustration.

The jump from ~/work to /home/user/work may also not be obvious to every user, especially those that are unfamiliar with unix shells.

Copy link
Author

@marbx marbx Aug 20, 2023 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please create such a subsection, and you are welcome to copy my text, which I then remove from this PR.
Ideally we can work on this branch, Git allows this.

I agree that ~/ could confuse Windows users, but I just wanted to be consistent with the documentation.

Shall I replace the 13 cases of ~/' with /home/user/`in 040_backup alone, or do you want to do that?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about a plain We backed up the absolute path ..., so the snapshot contains the full path: followed by the output of ls?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally think documentation should contain a path like /home/user/work as example for an absolute path.

within the snapshot is ``/home/user/work``.

If we attach a relative path ``work``, the path within the snaphot is ``/work``.

For example ``restic backup work`` run from ``/home/user`` creates a snapshot
with a directory ``/home/user/work`` that contains the path ``/work``
within the snapshot. This path-related discrepancy applies to each command
that tries to access data within a snapshot. You can lookup the paths within
a repository using the ``ls latest /`` command.

If you don't pass the ``--verbose`` option, restic will print less data. You'll
still get a nice live status display. Be aware that the live status shows the
processed files and not the transferred data. Transferred volume might be lower
Expand Down
3 changes: 3 additions & 0 deletions doc/045_working_with_repos.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ Now, you can list all the snapshots stored in the repository:
590c8fc8 2015-05-08 21:47:38 kazik /srv
9f0bc19e 2015-05-08 21:46:11 luigi /srv

The Directory column shows the attached path, which may differ
from the path within the repository, see https://restic.readthedocs.io/en/stable/040_backup.html#backing-up for details of this discrepancy.

You can filter the listing by directory path:

.. code-block:: console
Expand Down
25 changes: 25 additions & 0 deletions doc/050_restore.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,31 @@ e.g.:

$ restic -r /srv/restic-repo dump --path /production.sql latest production.sql | mysql

This example assumes you ran a backup using an absolute path, which coincides with the
path within the snaphots.
See https://restic.readthedocs.io/en/stable/040_backup.html#backing-up for the difference
between the path used to create the repository and the paths within the snaphots.

If you ran a backup using the relative path ``work/``, the ``dump`` command would look like:

.. code-block:: console

$ restic -r /srv/restic-repo dump latest /work/README.md


If dump results in the error message ``cannot dump file: path "/home" not found in snapshot``
first double check you used the path within the snaphot, using the ``ls latest /`` command,
which for the repository above results in:

.. code-block:: console

$ restic -r /srv/restic-repo ls latest /
enter password for repository:
snapshot 1541acae of [/home/other/work] filtered by [/] at 2023-08-09 04:00:03.533117139 +0200 CEST):
/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
output the contents in the tar (default) or zip format:
Expand Down