feat(docs): Add documentation for the rewrite command

[s-leroux]

This adds documentation for the rewrite command, explaining how to modify existing snapshots.

It's a first draft focussing only on removing files.

[aawsome]

Thanks @s-leroux for the draft.

First, there are improvements for rewrite on the way giving more options and adding by default a rewrite tag. So, please wait until they land in nightly (maybe today or tomorrow).

One comment: instead of using rustic find to find affected snapshots, using -n outputs which snapshots would be modified by the given rewrite options (and omits the ones which are not affected) - so maybe this should be shown in the docu?

[s-leroux]

First, there are improvements for rewrite on the way giving more options and adding by default a rewrite tag. So, please wait until they land in nightly (maybe today or tomorrow).

No problem: I was busy all week, so I didn't have time to work on that anyway.

• rewrite -n instead of/as a complement to find
• rewrite extra options
• default tagging

[aawsome]

see rustic-rs/rustic_core#465 (is included in the nightly builds already)

[s-leroux]

I have updated my PR as best I could.
However, I didn't have the time to detail all the rustic rewrite options.

Let me know if any changes are needed.

---

Remark: I noticed we cannot combine several rewrite operations in one command, like:

$ rustic rewrite --add-tags ... --remove-tags ...
<error>

Is this a design choice?

Notably, if we could use both --glob and --add-tags in the same command, --tags-rewritten becomes redundant. Speaking of that, I used --tags-rewritten '' in the docs. Is it the canonical way to prevent the rewrite auto-tagging?

[aawsome]

Hi @s-leroux Actually you can use --glob in combination with --add-tags. There is only a restriction about combining --add-tags and --remove-tags which I consider to be a bug. I'll fix that.

[aawsome]

Speaking of that, I used --tags-rewritten '' in the docs. Is it the canonical way to prevent the rewrite auto-tagging?

It this the preferred way unless you use --force which by default does not tag the new, but remove the old snapshots. But this can also be overwritten by setting --tags-rewritten.