Having trouble finding documentation for "Include / Exclude Patterns". Does the order matter? What's the difference between /dirname/, /dirname/*, /dirname/**, /dirname/***...?

[OwenAR]

Hi, I just started using timeshift,
and I'm having trouble finding documentation for "Include / Exclude Patterns".

Like, the gui tells you "Drag-drop to re-order", but it doesn't explain:
Does the order matter?
If so, how?

And I've seen patterns like:
/dirname/
/dirname/*
/dirname/**
and even
/dirname/***
but I don't understand what the differences are?

I would guess there should be a way to choose between backing up a dir /dirname/ normally,
and backing it up so its existence will be restored,
but its contents ignored?
(eg, what I would think you'd want if it was the automount point for an external harddrive you're not including in the back-up?)
... but I'm still confused as to which usage would be /dirname/ and which /dirname/*?

And I'm completely stumped on the meaning of ** and ***.
Are those some kind of shorthand for like {*,.*} or... something?

(And obviously, it would be nice if the gui could be tweaked to tell you this info, or at least where to find it.)

(
EDIT: also, if the order is important, then I'm also getting the bug where it keeps resetting it, and I have to manually edit /etc/timeshift.json, as mentioned in #626

I'm pretty sure I'm experiencing #789 too, but since nobody has responded to that,
I'm not sure if that's actually a bug, or just us not understanding how it's supposed to work cuz there's no documentation obvious to us
)

[teejee2008]

Filter order is important. Filters are applied from top-to-bottom on each file and folder. For each file, the first matching filter is applied and the rest are ignored.

It is explained in the Rsync user manual:
https://download.samba.org/pub/rsync/rsync.html

[OwenAR]

Ohhh, thanks, that explains why I couldn't find anything: I was searching for info on timeshift for the asterisk stuff etc, when I should've been looking for info on rsync
(I also just started using rsync like barely a few days before timeshift.)

So... I still have a couple questions, and I guess this isn't really the right place to ask this, but even if you can't answer, maybe you could at least tell me where I should ask...
(I'm nervous about just experimenting with things and risking making a mess that I couldn't restore cuz restoring is exactly what I messed up)

Right now, I have in my /etc/timeshift.json:

{
  "backup_device_uuid" : "4df3b721-cc04-4294-9d9b-db87e1712b06",
  "parent_device_uuid" : "NAL14N-vhh2-suQv-sWkv-cfhB-vaSV-genogs",
  "do_first_run" : "false",
  "btrfs_mode" : "false",
  "include_btrfs_home_for_backup" : "false",
  "include_btrfs_home_for_restore" : "false",
  "stop_cron_emails" : "true",
  "btrfs_use_qgroup" : "true",
  "schedule_monthly" : "false",
  "schedule_weekly" : "false",
  "schedule_daily" : "false",
  "schedule_hourly" : "false",
  "schedule_boot" : "false",
  "count_monthly" : "2",
  "count_weekly" : "3",
  "count_daily" : "5",
  "count_hourly" : "6",
  "count_boot" : "5",
  "snapshot_size" : "49039865075",
  "snapshot_count" : "532769",
  "date_format" : "%Y-%m-%d %H:%M:%S",
  "exclude" : [
    "/home/o1/.dropbox/***",
    "/home/o1/.dropbox-dist/***",
    "/home/o1/Dropbox/***",
    "+ /home/o1/***",
    "/ehds/**",
    "/media/**",
    "+ /root/***"
  ],
  "exclude-apps" : [
  ]
}

---

First question:

My intention with:
/home/o1/.dropbox/***
/home/o1/.dropbox-dist/***
/home/o1/Dropbox/***
+ /home/o1/***
is to capture the state of my homedir,
so that it would get restored to the state of that snapshot
but have the restoration not alter the state of any of that dropbox stuff.

Did I get that right?

You said "the first matching filter is applied and the rest are ignored"
so if I'm understanding that correctly,
that means my more specific dropbox exclude rules match and apply first
and then the include rule + /home/o1/*** has not matched yet, so it will apply next?

Whereas if I did it the other was around,
the include rule + /home/o1/*** would match first
(I mean, since /home/o1/*** itself matches /home/o1/Dropbox/***),
so the exclude rules would be ignored?

(
... It just... feels a bit weird,
because conceptually, it feels like I'm like cutting holes, and then laying down a blanket,
so I don't feel comfortable that I actually understood it right...
)

---

Second question:

I have the exclude rules there
/media/**
/ehds/**
(for "External HardDriveS", a dir I made while messing around trying to figure out how to set up automounting properly)

My intention is to not include any of the contents of those dirs in a snapshot,
but to capture the dirs themselves (ie, their existence, and... whatever state they themselves have, permissions or whatever),
so that, hypothetically, if I deleted the dir
(or modified its permissions/ownership/etc (what else is there in that "etc" anyway? access/modify dates?)),
then restoring the snapshot would put it back, just the way it was.

So I used ** cuz the documentation says:

a trailing "dir_name/***" will match both
the directory (as if "dir_name/" had been specified)
and
everything in the directory (as if "dir_name/**" had been specified).
which I think implies that /ehds/** matches "everything in the directory", but not /ehds/ itself.

Did I get that right?

[teejee2008]

That's correct.

The top-down approach may feel weird but it is the most flexible way of defining the exclude/include filters.

[zaits07]

Is there some posibility to override timeshift default exclude list?

Default exclude rules hardcoded in timeshift, and it prepend result "exclude.list" for rsync.

Rsync docs say "The exclude patterns actually short-circuit the directory traversal stage ... rsync did not descend through that excluded section of the hierarchy".

So i can't backup "/mnt/special/folder/" because of hardcoded exclude rule "/mnt/*".

[zaits07]

sorry, it will be solved by #796