Using grouping patterns

When FSVS walks through your working copy it tries to find new (ie. not yet versioned) entries. Every new entry gets tested against the defined grouping patterns (in the given order!); if a pattern matches, the corresponding group is assigned to the entry, and no further matching is done.

See also entry statii.

Ignore patterns are used to ignore certain directory entries, where versioning makes no sense. If you're versioning the complete installation of a machine, you wouldn't care to store the contents of /proc (see man 5 proc), or possibly because of security reasons you don't want /etc/shadow , /etc/sshd/ssh_host_*key , and/or other password- or key-containing files.

Ignore patterns allow you to define which directory entries (files, subdirectories, devices, symlinks etc.) should be taken, respectively ignored.

The grouping patterns can be compared with the auto-props feature of subversion; it allows automatically defining properties for new entries, or ignoring them, depending on various criteria.

For example you might want to use encryption for the files in your users' .ssh directory, to secure them against unauthorized access in the repository, and completely ignore the private key files:

Grouping patterns:

    group:ignore,/home/*/.ssh/id*
    group:encrypt,/home/*/.ssh/**

And the $FSVS_CONF/groups/encrypt file would have a definition for the fsvs:commit-pipe (see the special properties).

A group definition file looks like this:

• Whitespace on the beginning and the end of the line is ignored.
• Empty lines, and lines with the first non-whitespace character being '#' (comments) are ignored.
• It can have either the keywords ignore or take; if neither is specified, the group ignore has ignore as default (surprise, surprise!), and all others use take.
• An arbitrary (small) number of lines with the syntax
  auto-prop property-name property-value can be given; property-name may not include whitespace, as there's no parsing of any quote characters yet.

An example:

   # This is a comment
     # This is another
   auto-props    fsvs:commit-pipe    gpg -er admin@my.net
   # End of definition

While an ignore pattern just needs the pattern itself (in one of the formats below), there are some modifiers that can be additionally specified:

   [group:{name},][dir-only,][insens|nocase,][take,][mode:A:C,]pattern

These are listed in the section Modifiers below.

These kinds of ignore patterns are available:

These must start with ./, just like a base-directory-relative path. ? , * as well as character classes [a-z] have their usual meaning, and ** is a wildcard for directory levels.

You can use a backslash \ outside of character classes to match some common special characters literally, eg. \* within a pattern will match a literal asterisk character within a file or directory name. Within character classes all characters except ] are treated literally. If a literal ] should be included in a character class, it can be placed as the first character or also be escaped using a backslash.

Example for / as the base-directory

     ./[oa]pt
     ./sys
     ./proc/*
     ./home/**~

This would ignore files and directories called apt or opt in the root directory (and files below, in the case of a directory), the directory /sys and everything below, the contents of /proc (but take the directory itself, so that upon restore it gets created as a mountpoint), and all entries matching *~ in and below /home .

Note:

If you're deep within your working copy and you'd like to ignore some files with a WC-relative ignore pattern, you might like to use the rel-ignore command.

         /etc/**.dpkg-old
         /etc/**.dpkg-bak
         /**.bak
         /**~

PCRE stands for Perl Compatible Regular Expressions; you can read about them with man pcre2 (if the manpages are installed), and/or perldoc perlre (if perldoc is installed).
If both fail for you, just google it.

These patterns have the form PCRE:{pattern}, with PCRE in uppercase.

An example:

     PCRE:./home/.*~

This one achieves exactly the same as ./home/**~ .

Another example:

     PCRE:./home/[a-s]

This would match /home/anthony , /home/guest , /home/somebody and so on, but would not match /home/theodore .

One more:

     PCRE:./.*(.(tmp|bak|sik|old|dpkg-96

Note that the pathnames start with ./ , just like above, and that the patterns are anchored at the beginning. To additionally anchor at the end you could use a $ at the end.

Another form to discern what is needed and what not is possible with DEVICE:[<|<=|>|>=]major[:minor].

This takes advantage of the major and minor device numbers of inodes (see man 1 stat and man 2 stat).

The rule is as follows:

• Directories have their parent matched against the given string
• All other entries have their own device matched.

This is because mount-points (ie. directories where other filesystems get attached) show the device of the mounted device, but should be versioned (as they are needed after restore); all entries (and all binding mounts) below should not.

The possible options <= or >= define a less-or-equal-than respective bigger-or-equal-than relationship, to ignore a set of device classes.

Examples:

     tDEVICE:3
     ./*

This patterns would define that all filesystems on IDE-devices (with major number 3) are taken , and all other files are ignored.

    DEVICE:0

This would ignore all filesystems with major number 0 - in linux these are the virtual filesystems ( proc , sysfs , devpts , etc.; see /proc/filesystems , the lines with nodev ).

Mind NFS and smb-mounts, check if you're using md , lvm and/or device-mapper !

Note: The values are parsed with strtoul() , so you can use decimal, hexadecimal (by prepending '0x', like '0x102') and octal ('0', like '0777') notation.

At last, another form to ignore entries is to specify them via the device they are on and their inode:

     INODE:major:minor:inode

This can be used if a file can be hardlinked to many places, but only one copy should be stored. Then one path can be marked as to take , and other instances can get ignored.

Note:

All of these patterns can have one or more of these modifiers before them, with (currently) optional ',' as separators; not all combinations make sense.

For patterns with the m (mode match) or d (dironly) modifiers the filename pattern gets optional; so you don't have to give an all-match wildcard pattern (./**) for these cases.

     take,dironly,./var/vmail/**
     take,./var/vmail/**/.*.sieve
     ./var/vmail/**

     take,dironly,./var/vmail/*
     take,dironly,./var/vmail/*/*
     take,./var/vmail/*/*/.*.sieve
     ./var/vmail/**

     mode:04:0
     take,./etc/
     ./**

Generated automatically by Doxygen for fsvs from the source code.