Confusing/wrong documentation on group-by flag

I am running what I believe to be the current version of restic (restic 0.15.2 compiled with go1.20.3 on linux/arm64) and after reading docs I was completely confused about “group-by” flag.

Reading the docs I assumed that I can use group-by option with backup command. Restic 0.15.2 documentation has a whole paragraph on using the group-by in the “Backing-up” section under “File change detection”:

“The previous backup snapshot, called “parent” snaphot in restic terminology, is determined as follows. By default restic groups snapshots by hostname and backup paths, and then selects the latest snapshot in the group that matches the current backup. You can change the selection criteria using the --group-by option, which defaults to host,paths. To select the latest snapshot with the same paths independent of the hostname, use paths. Or, to only consider the hostname and tags, use host,tags. Alternatively, it is possible to manually specify a specific parent snapshot using the --parent option. Finally, note that one would normally set the --group-by option for the forget command to the same value.”

Further in the manual “./restic backup --help” output is shown with group-by flag in the output.

However when I try to use group-by flag with backup command i get “unknown flag: --group-by”. It’s also not shown as a valid flag when I run “./restic backup --help”.

Can you directly link to the documentation you are talking about? In the docs Backing up (0.15.2). “group” is never mentioned.

restic backup --help has no option --group-by, neither. (Are you sure that you are using a consistent version of restic? Is restic and ./restic the same version on your system?)

restic snapshots has it, for instance, and there it works.

The feature was added by this PR:

I think it did not make to 0.15.2 release…

@pwsnla - if you are using restic 0.15.2 then please use Restic Documentation — restic 0.15.2 documentation

If you want the latest and greatest then use the latest documentation and restic binary you compile yourself from github - then you will have --group-by option available and documented

On docs website you can choose which version you want to see:

1 Like

Thank you for your reply. I thought I was using docs for v0.15.2. I did use Google search but the window that I opened from search results says “Backing up - restic 0.15.2 documentation” and it does contain description of “group-by” flag, hence my confusion. See attached screenshot:

I am not sure what sets the title of the window but that made me believe that I was looking at 0.15.2 docs.

Yes you are right - window title is misleading. It always show sthe latest available numeric restic version for latest and stable.

You could maybe try to fix it and submit PR:)

There’s now a issue for that at Title of is confusing · Issue #4420 · restic/restic · GitHub

1 Like