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.

[aawsome]

@s-leroux I merged this as having this in the docu is much better than having nothing! You can make a future PR if you want to update/change anything.
I think I'll try to talk about rustic tag. This is basically just a shortcut for rustic rewrite with the tag options..

[s-leroux]

3 févr. 2026 15:21:56 aawsome ***@***.***>:

There is only a restriction about combining *--add-tags* and *--remove-tags* which I consider to be a bug.

Ok, I will look at that and rephrase (or mention it as a temporary limitation). I see there are other messages; I will answer one by one. ;)

[s-leroux]

3 févr. 2026 15:23:21 aawsome ***@***.***>:

It this the preferred way unless you use *--force* which by default does not tag the new, but remove the old snapshots.

I noticed that several times: you talk about the '--force' option. Isn't it the '--forget' option instead? If for whatever reason you want to keep both the original and the rewritten one **without an extra tag** ` --tags-rewritten ''` remains the answer, or it isn't?

[s-leroux]

13 févr. 2026 21:04:17 aawsome ***@***.***>:

[Image]*aawsome* left a comment (rustic-rs/docs#121)[#121 (comment)] @s-leroux[https://github.com/s-leroux] I merged this as having this in the docu is much better than having nothing! You can make a future PR if you want to update/change anything. I think I'll try to talk about *rustic tag*. This is basically just a shortcut for *rustic rewrite* with the tag options.. — Reply to this email directly, view it on GitHub[#121 (comment)], or unsubscribe[https://github.com/notifications/unsubscribe-auth/AAMZ47TRV3NMURUHYYMFXGT4LYU35AVCNFSM6AAAAACSVTL7A6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQOJZGE4DONBXG4]. You are receiving this because you were mentioned. [Image de pistage][https://github.com/notifications/beacon/AAMZ47SNC4Q45IGID5CFODD4LYU35A5CNFSM6AAAAACSVTL7A6WGG33NNVSW45C7OR4XAZNMJFZXG5LFINXW23LFNZ2KUY3PNVWWK3TUL5UWJTXINDQRK.gif]

Ok. Thanks for the merge. I will look at the updates you mentioned earlier and submit another PR if I update the docs. 🙏

[aawsome]

3 févr. 2026 15:23:21 aawsome @.***>:
It this the preferred way unless you use --force which by default does not tag the new, but remove the old snapshots.
I noticed that several times: you talk about the '--force' option. Isn't it the '--forget' option instead? If for whatever reason you want to keep both the original and the rewritten one without an extra tag --tags-rewritten '' remains the answer, or it isn't?

Ah, sorry, yes I meant '--forget. For --forget --tags-rewrittenis by default empty, whereas it isrewriteif no--forgetis given. So,--tags-rewritten ''does not add a an extra tag to the new snapshots, also if no--forget` is chosen.

[aawsome]

3 févr. 2026 15:21:56 aawsome @.***>:
There is only a restriction about combining --add-tags and --remove-tags which I consider to be a bug.

Just realized that I forgot to fix that. I just made rustic-rs/rustic_core#476, but that will be only in the next release...