github.com/mckael/restic@v0.8.3/doc/060_forget.rst (about) 1 .. 2 Normally, there are no heading levels assigned to certain characters as the structure is 3 determined from the succession of headings. However, this convention is used in Python’s 4 Style Guide for documenting which you may follow: 5 6 # with overline, for parts 7 * for chapters 8 = for sections 9 - for subsections 10 ^ for subsubsections 11 " for paragraphs 12 13 ######################### 14 Removing backup snapshots 15 ######################### 16 17 All backup space is finite, so restic allows removing old snapshots. 18 This can be done either manually (by specifying a snapshot ID to remove) 19 or by using a policy that describes which snapshots to forget. For all 20 remove operations, two commands need to be called in sequence: 21 ``forget`` to remove a snapshot and ``prune`` to actually remove the 22 data that was referenced by the snapshot from the repository. This can 23 be automated with the ``--prune`` option of the ``forget`` command, 24 which runs ``prune`` automatically if snapshots have been removed. 25 26 It is advisable to run ``restic check`` after pruning, to make sure 27 you are alerted, should the internal data structures of the repository 28 be damaged. 29 30 Remove a single snapshot 31 ************************ 32 33 The command ``snapshots`` can be used to list all snapshots in a 34 repository like this: 35 36 .. code-block:: console 37 38 $ restic -r /tmp/backup snapshots 39 enter password for repository: 40 ID Date Host Tags Directory 41 ---------------------------------------------------------------------- 42 40dc1520 2015-05-08 21:38:30 kasimir /home/user/work 43 79766175 2015-05-08 21:40:19 kasimir /home/user/work 44 bdbd3439 2015-05-08 21:45:17 luigi /home/art 45 590c8fc8 2015-05-08 21:47:38 kazik /srv 46 9f0bc19e 2015-05-08 21:46:11 luigi /srv 47 48 In order to remove the snapshot of ``/home/art``, use the ``forget`` 49 command and specify the snapshot ID on the command line: 50 51 .. code-block:: console 52 53 $ restic -r /tmp/backup forget bdbd3439 54 enter password for repository: 55 removed snapshot d3f01f63 56 57 Afterwards this snapshot is removed: 58 59 .. code-block:: console 60 61 $ restic -r /tmp/backup snapshots 62 enter password for repository: 63 ID Date Host Tags Directory 64 ---------------------------------------------------------------------- 65 40dc1520 2015-05-08 21:38:30 kasimir /home/user/work 66 79766175 2015-05-08 21:40:19 kasimir /home/user/work 67 590c8fc8 2015-05-08 21:47:38 kazik /srv 68 9f0bc19e 2015-05-08 21:46:11 luigi /srv 69 70 But the data that was referenced by files in this snapshot is still 71 stored in the repository. To cleanup unreferenced data, the ``prune`` 72 command must be run: 73 74 .. code-block:: console 75 76 $ restic -r /tmp/backup prune 77 enter password for repository: 78 79 counting files in repo 80 building new index for repo 81 [0:00] 100.00% 22 / 22 files 82 repository contains 22 packs (8512 blobs) with 100.092 MiB bytes 83 processed 8512 blobs: 0 duplicate blobs, 0B duplicate 84 load all snapshots 85 find data that is still in use for 1 snapshots 86 [0:00] 100.00% 1 / 1 snapshots 87 found 8433 of 8512 data blobs still in use 88 will rewrite 3 packs 89 creating new index 90 [0:00] 86.36% 19 / 22 files 91 saved new index as 544a5084 92 done 93 94 Afterwards the repository is smaller. 95 96 You can automate this two-step process by using the ``--prune`` switch 97 to ``forget``: 98 99 .. code-block:: console 100 101 $ restic forget --keep-last 1 --prune 102 snapshots for host mopped, directories /home/user/work: 103 104 keep 1 snapshots: 105 ID Date Host Tags Directory 106 ---------------------------------------------------------------------- 107 4bba301e 2017-02-21 10:49:18 mopped /home/user/work 108 109 remove 1 snapshots: 110 ID Date Host Tags Directory 111 ---------------------------------------------------------------------- 112 8c02b94b 2017-02-21 10:48:33 mopped /home/user/work 113 114 1 snapshots have been removed, running prune 115 counting files in repo 116 building new index for repo 117 [0:00] 100.00% 37 / 37 packs 118 repository contains 37 packs (5521 blobs) with 151.012 MiB bytes 119 processed 5521 blobs: 0 duplicate blobs, 0B duplicate 120 load all snapshots 121 find data that is still in use for 1 snapshots 122 [0:00] 100.00% 1 / 1 snapshots 123 found 5323 of 5521 data blobs still in use, removing 198 blobs 124 will delete 0 packs and rewrite 27 packs, this frees 22.106 MiB 125 creating new index 126 [0:00] 100.00% 30 / 30 packs 127 saved new index as b49f3e68 128 done 129 130 Removing snapshots according to a policy 131 **************************************** 132 133 Removing snapshots manually is tedious and error-prone, therefore restic 134 allows specifying which snapshots should be removed automatically 135 according to a policy. You can specify how many hourly, daily, weekly, 136 monthly and yearly snapshots to keep, any other snapshots are removed. 137 The most important command-line parameter here is ``--dry-run`` which 138 instructs restic to not remove anything but print which snapshots would 139 be removed. 140 141 When ``forget`` is run with a policy, restic loads the list of all 142 snapshots, then groups these by host name and list of directories. The grouping 143 options can be set with ``--group-by``, to only group snapshots by paths and 144 tags use ``--group-by paths,tags``. The policy is then applied to each group of 145 snapshots separately. This is a safety feature. 146 147 The ``forget`` command accepts the following parameters: 148 149 - ``--keep-last n`` never delete the ``n`` last (most recent) snapshots 150 - ``--keep-hourly n`` for the last ``n`` hours in which a snapshot was 151 made, keep only the last snapshot for each hour. 152 - ``--keep-daily n`` for the last ``n`` days which have one or more 153 snapshots, only keep the last one for that day. 154 - ``--keep-weekly n`` for the last ``n`` weeks which have one or more 155 snapshots, only keep the last one for that week. 156 - ``--keep-monthly n`` for the last ``n`` months which have one or more 157 snapshots, only keep the last one for that month. 158 - ``--keep-yearly n`` for the last ``n`` years which have one or more 159 snapshots, only keep the last one for that year. 160 - ``--keep-tag`` keep all snapshots which have all tags specified by 161 this option (can be specified multiple times). 162 163 Additionally, you can restrict removing snapshots to those which have a 164 particular hostname with the ``--hostname`` parameter, or tags with the 165 ``--tag`` option. When multiple tags are specified, only the snapshots 166 which have all the tags are considered. For example, the following command 167 removes all but the latest snapshot of all snapshots that have the tag ``foo``: 168 169 .. code-block:: console 170 171 $ restic forget --tag foo --keep-last 1 172 173 This command removes all but the last snapshot of all snapshots that have 174 either the ``foo`` or ``bar`` tag set: 175 176 .. code-block:: console 177 178 $ restic forget --tag foo --tag bar --keep-last 1 179 180 To only keep the last snapshot of all snapshots with both the tag ``foo`` and 181 ``bar`` set use: 182 183 .. code-block:: console 184 185 $ restic forget --tag foo,tag bar --keep-last 1 186 187 All the ``--keep-*`` options above only count 188 hours/days/weeks/months/years which have a snapshot, so those without a 189 snapshot are ignored. 190 191 For safety reasons, restic refuses to act on an "empty" policy. For example, 192 if one were to specify ``--keep-last 0`` to forget *all* snapshots in the 193 repository, restic will respond that no snapshots will be removed. To delete 194 all snapshots, use ``--keep-last 1`` and then finally remove the last 195 snapshot ID manually (by passing the ID to ``forget``). 196 197 All snapshots are evaluated against all matching ``--keep-*`` counts. A 198 single snapshot on 2017-09-30 (Sun) will count as a daily, weekly and monthly. 199 200 Let's explain this with an example: Suppose you have only made a backup 201 on each Sunday for 12 weeks. Then ``forget --keep-daily 4`` will keep 202 the last four snapshots for the last four Sundays, but remove the rest. 203 Only counting the days which have a backup and ignore the ones without 204 is a safety feature: it prevents restic from removing many snapshots 205 when no new ones are created. If it was implemented otherwise, running 206 ``forget --keep-daily 4`` on a Friday would remove all snapshots! 207 208 Another example: Suppose you make daily backups for 100 years. Then 209 ``forget --keep-daily 7 --keep-weekly 5 --keep-monthly 12 --keep-yearly 75`` 210 will keep the most recent 7 daily snapshots, then 4 (remember, 7 dailies 211 already include a week!) last-day-of-the-weeks and 11 or 12 212 last-day-of-the-months (11 or 12 depends if the 5 weeklies cross a month). 213 And finally 75 last-day-of-the-year snapshots. All other snapshots are 214 removed. 215