Documentation/bup-prune-older.md

   1 % bup-prune-older(1) bup %BUP_VERSION% | bup %BUP_VERSION%
   2 % Rob Browning <rlb@defaultvalue.org>
   3 % %BUP_DATE%
   4
   5 # NAME
   6
   7 bup-prune-older - remove older saves (CAUTION: EXPERIMENTAL)
   8
   9 # SYNOPSIS
  10
  11 bup prune-older [options...] <*branch*...>
  12
  13 # DESCRIPTION
  14
  15 `bup prune-older` removes (permanently deletes) all saves except those
  16 preserved by the various keep arguments detailed below.  At least one
  17 keep argument must be specified.  This command is equivalent to a
  18 suitable `bup rm` invocation followed by `bup gc`.
  19
  20 WARNING: This is one of the few bup commands that modifies your
  21 archive in intentionally destructive ways.  Though if an attempt to
  22 `join` or `restore` the data you still care about after a
  23 `prune-older` succeeds, that's a fairly encouraging sign that the
  24 commands worked correctly.  (The `t/compare-trees` command in the
  25 source tree can be used to help test before/after results.)
  26
  27 # KEEP PERIODS
  28
  29 A `--keep` PERIOD (as required below) must be an integer followed by a
  30 scale, or "forever".  For example, 12y specifies a PERIOD of twelve
  31 years.  Here are the valid scales:
  32
  33   - s indicates seconds
  34   - min indicates minutes (60s)
  35   - h indicates hours (60m)
  36   - d indicates days (24h)
  37   - w indicates weeks (7d)
  38   - m indicates months (31d)
  39   - y indicates years (366d)
  40   - forever is infinitely far in the past
  41
  42 As indicated, the PERIODS are computed with respect to the current
  43 time, or the `--wrt` value if specified, and do not respect any
  44 calendar, so `--keep-dailies-for 5d` means a period starting exactly
  45 5 * 24 * 60 * 60 seconds before the starting point.
  46
  47 # OPTIONS
  48
  49 --keep-all-for PERIOD
  50 :   when no smaller time scale --keep option applies, retain all saves
  51     within the given period.
  52
  53 --keep-dailies-for PERIOD
  54 :   when no smaller time scale --keep option applies, retain the
  55     oldest save for any day within the given period.
  56
  57 --keep-monthlies-for PERIOD
  58 :   when no smaller time scale --keep option applies, retain the
  59     oldest save for any month within the given period.
  60
  61 --keep-yearlies-for PERIOD
  62 :   when no smaller time scale --keep option applies, retain the
  63     oldest save for any year within the given period.
  64
  65 --keep ALL,DAILY,MONTHLY,YEARLY
  66 :   shorthand equivalent to specifying each of the related `--keep-*`
  67     options for each period.  If an underscore is specified for a
  68     period, then that time-scale will be unaffected by this argument.
  69
  70 --wrt UTC_SECONDS
  71 :   when computing a keep period, place the most recent end of the
  72     range at UTC\_SECONDS, and any saves newer than this will be kept.
  73
  74 --pretend
  75 :   don't do anything, just list the actions that would be taken to
  76     standard output, one action per line like this:
  77
  78         - SAVE
  79         + SAVE
  80         ...
  81
  82 --gc
  83 :   garbage collect the repository after removing the relevant saves.
  84     This is the default behavior, but it can be avoided with `--no-gc`.
  85
  86 \--gc-threshold N
  87 :   only rewrite a packfile if it's over N percent garbage; otherwise
  88     leave it alone.  The default threshold is 10%.
  89
  90 -*#*, \--compress *#*
  91 :   set the compression level when rewriting archive data to # (a
  92     value from 0-9, where 9 is the highest and 0 is no compression).
  93     The default is 1 (fast, loose compression).
  94
  95 -v, \--verbose
  96 :   increase verbosity (can be specified more than once).
  97
  98 # NOTES
  99
 100 When `--verbose` is specified, the save periods will be summarized to
 101 standard error with lines like this:
 102
 103     keeping monthlies since 1969-07-20-201800
 104     keeping all yearlies
 105     ...
 106
 107 It's possible that the current implementation might not be able to
 108 format the date if, for example, it is far enough back in time.  In
 109 that case, you will see something like this:
 110
 111     keeping yearlies since -30109891477 seconds before 1969-12-31-180000
 112     ...
 113
 114 # EXAMPLES
 115
 116     # Keep all saves for the past month, and any older monthlies for
 117     # the past year.  Delete everything else.
 118     $ bup prune-older --keep-all-for 1m --keep-monthlies-for 1y
 119
 120     # Keep all saves for the past 6 months and delete everything else,
 121     # but only on the semester branch.
 122     $ bup prune-older --keep-all-for 6m semester
 123
 124 # SEE ALSO
 125
 126 `bup-rm`(1), `bup-gc`(1), and `bup-fsck`(1)
 127
 128 # BUP
 129
 130 Part of the `bup`(1) suite.