.TH "FSVS - Group definitions" 5 "11 Mar 2010" "Version trunk:2424" "fsvs" \" -*- nroff -*- .ad l .nh .SH NAME Using grouping patterns \- .PP Patterns are used to define groups for new entries; a group can be used to ignore the given entries, or to automatically set properties when the entry is taken on the entry list. Patterns are used to define groups for new entries; a group can be used to ignore the given entries, or to automatically set properties when the entry is taken on the entry list. So the auto-props are assigned when the entry gets put on the internal list; that happens for the \fBadd\fP, \fBprop-set\fP or \fBprop-del\fP, and of course \fBcommit\fP commands. .br To override the auto-props of some new entry just use the property commands. .SH "Overview" .PP When \fCFSVS\fP walks through your working copy it tries to find \fBnew\fP (ie. not yet versioned) entries. Every \fBnew\fP 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. .PP See also \fBentry statii\fP. .SS "Predefined group 1: 'ignore'" If an entry gets a group named \fC'ignore'\fP assigned, it will not be considered for versioning. .PP This is the only \fBreally\fP special group name. .SS "Predefined group 2: 'take'" This group mostly specifies that no further matching is to be done, so that later \fBignore\fP patterns are not tested. .PP Basically the \fC'take'\fP group is an ordinary group like all others; it is just predefined, and available with a \fBshort-hand notation\fP. .SH "Why should I ignore files?" .PP 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 \fC/proc\fP (see \fCman 5 proc\fP), or possibly because of security reasons you don't want \fC/etc/shadow\fP , \fC/etc/sshd/ssh_host_*key\fP , and/or other password- or key-containing files. .PP Ignore patterns allow you to define which directory entries (files, subdirectories, devices, symlinks etc.) should be taken, respectively ignored. .SH "Why should I assign groups?" .PP The grouping patterns can be compared with the \fCauto-props\fP feature of subversion; it allows automatically defining properties for new entries, or ignoring them, depending on various criteria. .PP For example you might want to use encryption for the files in your users' \fC\fP.ssh directory, to secure them against unauthorized access in the repository, and completely ignore the private key files: .PP Grouping patterns: .PP .nf group:ignore,/home/*/.ssh/id* group:encrypt,/home/*/.ssh/** .fi .PP And the \fC$FSVS_CONF/groups/encrypt\fP file would have a definition for the \fCfsvs:commit-pipe\fP (see the \fBspecial properties\fP). .SH "Syntax of group files" .PP A group definition file looks like this: .PD 0 .IP "\(bu" 2 Whitespace on the beginning and the end of the line is ignored. .IP "\(bu" 2 Empty lines, and lines with the first non-whitespace character being \fC'#'\fP (comments) are ignored. .IP "\(bu" 2 It can have \fBeither\fP the keywords \fCignore\fP or \fCtake\fP; if neither is specified, the group \fCignore\fP has \fCignore\fP as default (surprise, surprise!), and all others use \fCtake\fP. .IP "\(bu" 2 An arbitrary (small) number of lines with the syntax .br \fCauto-prop \fIproperty-name\fP \fIproperty-value\fP\fP can be given; \fIproperty-name\fP may not include whitespace, as there's no parsing of any quote characters yet. .PP .PP An example: .PP .nf # This is a comment # This is another auto-props fsvs:commit-pipe gpg -er admin@my.net # End of definition .fi .PP .SH "Specification of groups and patterns" .PP While an ignore pattern just needs the pattern itself (in one of the formats below), there are some modifiers that can be additionally specified: .PP .nf [group:{name},][dir-only,][insens|nocase,][take,][mode:A:C,]pattern .fi .PP These are listed in the section \fBModifiers\fP below. .PP These kinds of ignore patterns are available: .SH "Shell-like patterns" .PP These must start with \fC./\fP, just like a base-directory-relative path. \fC\fP? , \fC*\fP as well as character classes \fC\fP[a-z] have their usual meaning, and \fC**\fP is a wildcard for directory levels. .PP You can use a backslash \fC\\\fP outside of character classes to match some common special characters literally, eg. \fC\\*\fP within a pattern will match a literal asterisk character within a file or directory name. Within character classes all characters except \fC\fP] are treated literally. If a literal \fC\fP] should be included in a character class, it can be placed as the first character or also be escaped using a backslash. .PP Example for \fC/\fP as the base-directory .PP .nf ./[oa]pt ./sys ./proc/* ./home/**~ .fi .PP .PP This would ignore files and directories called \fCapt\fP or \fCopt\fP in the root directory (and files below, in the case of a directory), the directory \fC/sys\fP and everything below, the contents of \fC/proc\fP (but take the directory itself, so that upon restore it gets created as a mountpoint), and all entries matching \fC*~\fP in and below \fC/home\fP . .PP \fBNote:\fP .RS 4 The patterns are anchored at the beginning and the end. So a pattern \fC./sys\fP will match \fBonly\fP a file or directory named \fCsys\fP. If you want to exclude a directories' files, but not the directory itself, use something like \fC./dir/*\fP or \fC./dir/**\fP .RE .PP 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 \fBrel-ignore\fP command. .SS "Absolute shell patterns" There is another way to specify shell patterns - using absolute paths. .br The syntax is similar to normal shell patterns; but instead of the \fC./\fP prefix the full path, starting with \fC/\fP, is used. .PP .PP .nf /etc/**.dpkg-old /etc/**.dpkg-bak /**.bak /**~ .fi .PP .PP The advantage of using full paths is that a later \fCdump\fP and \fCload\fP in another working copy (eg. when moving from versioning \fC/etc\fP to \fC/\fP) does simply work; the patterns don't have to be modified. .PP Internally this simply tries to remove the working copy base directory at the start of the patterns (on loading); then they are processed as usual. .PP If a pattern does \fBnot\fP match the wc base, and neither has the wild-wildcard prefix \fC/**\fP, a \fBwarning\fP is issued. .SH "PCRE-patterns" .PP PCRE stands for Perl Compatible Regular Expressions; you can read about them with \fCman pcre2\fP (if the manpages are installed), and/or \fCperldoc perlre\fP (if perldoc is installed). .br If both fail for you, just google it. .PP These patterns have the form \fCPCRE:{pattern}\fP, with \fCPCRE\fP in uppercase. .PP An example: .PP .nf PCRE:./home/.*~ .fi .PP This one achieves exactly the same as \fC./home/**~\fP . .PP Another example: .PP .nf PCRE:./home/[a-s] .fi .PP .PP This would match \fC/home/anthony\fP , \fC/home/guest\fP , \fC/home/somebody\fP and so on, but would not match \fC/home/theodore\fP . .PP One more: .PP .nf PCRE:./.*(\.(tmp|bak|sik|old|dpkg-\w+)|~)$ .fi .PP .PP Note that the pathnames start with \fC\fP./ , just like above, and that the patterns are anchored at the beginning. To additionally anchor at the end you could use a \fC$\fP at the end. .SH "Ignoring all files on a device" .PP Another form to discern what is needed and what not is possible with \fCDEVICE:[<|<=|>|>=]major[:minor]\fP. .PP This takes advantage of the major and minor device numbers of inodes (see \fCman 1 stat\fP and \fCman 2 stat\fP). .PP The rule is as follows: .IP "\(bu" 2 Directories have their parent matched against the given string .IP "\(bu" 2 All other entries have their own device matched. .PP .PP 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. .PP The possible options \fC<=\fP or \fC>=\fP define a less-or-equal-than respective bigger-or-equal-than relationship, to ignore a set of device classes. .PP Examples: .PP .nf tDEVICE:3 ./* .fi .PP This patterns would define that all filesystems on IDE-devices (with major number 3) are \fItaken\fP , and all other files are ignored. .PP .PP .nf DEVICE:0 .fi .PP This would ignore all filesystems with major number 0 - in linux these are the \fIvirtual\fP filesystems ( \fCproc\fP , \fCsysfs\fP , \fCdevpts\fP , etc.; see \fC/proc/filesystems\fP , the lines with \fCnodev\fP ). .PP Mind NFS and smb-mounts, check if you're using \fImd\fP , \fIlvm\fP and/or \fIdevice-mapper\fP ! .PP Note: The values are parsed with \fCstrtoul()\fP , so you can use decimal, hexadecimal (by prepending \fC'0x'\fP, like \fC'0x102'\fP) and octal (\fC'0'\fP, like \fC'0777'\fP) notation. .SH "Ignoring a single file, by inode" .PP At last, another form to ignore entries is to specify them via the device they are on and their inode: .PP .nf INODE:major:minor:inode .fi .PP 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 \fItake\fP , and other instances can get ignored. .PP \fBNote:\fP .RS 4 That's probably a bad example. There should be a better mechanism for handling hardlinks, but that needs some help from subversion. .RE .PP .SH "Modifiers" .PP All of these patterns can have one or more of these modifiers \fBbefore\fP them, with (currently) optional \fC','\fP as separators; not all combinations make sense. .PP For patterns with the \fCm\fP (mode match) or \fCd\fP (dironly) modifiers the filename pattern gets optional; so you don't have to give an all-match wildcard pattern (\fC./**\fP) for these cases. .SS "'take': Take pattern" This modifier is just a short-hand for assigning the group \fBtake\fP. .SS "'ignore': Ignore pattern" This modifier is just a short-hand for assigning the group \fBignore\fP. .SS "'insens' or 'nocase': Case insensitive" With this modifier you can force the match to be case-insensitive; this can be useful if other machines use eg. \fCsamba\fP to access files, and you cannot be sure about them leaving \fC'.BAK'\fP or \fC'.bak'\fP behind. .SS "'dironly': Match only directories" This is useful if you have a directory tree in which only certain files should be taken; see below. .SS "'mode': Match entries' mode" This expects a specification of two octal values in the form \fCm:\fIand_value\fP:\fIcompare_value\fP\fP, like \fCm:04:00\fP; the bits set in \fCand_value\fP get isolated from the entries' mode, and compared against \fCcompare_value\fP. .PP As an example: the file has mode \fC0750\fP; a specification of .PD 0 .IP "\(bu" 2 \fCm:0700:0700\fP matches, .IP "\(bu" 2 \fCm:0700:0500\fP doesn't; and .IP "\(bu" 2 \fCm:0007:0000\fP matches, but .IP "\(bu" 2 \fCm:0007:0007\fP doesn't. .PP .PP A real-world example: \fCm:0007:0000\fP would match all entries that have \fBno\fP right bits set for \fI'others'\fP, and could be used to exclude private files (like \fC/etc/shadow\fP). (Alternatively, the \fIothers-read\fP bit could be used: \fCm:0004:0000\fP. .PP FSVS will reject invalid specifications, ie. when bits in \fCcompare_value\fP are set that are cleared in \fCand_value:\fP these patterns can never match. .br An example would be \fCm:0700:0007\fP. .SS "Examples" .PP .nf take,dironly,./var/vmail/** take,./var/vmail/**/.*.sieve ./var/vmail/** .fi .PP This would take all \fC'.*.sieve'\fP files (or directories) below \fC/var/vmail\fP, in all depths, and all directories there; but no other files. .PP If your files are at a certain depth, and you don't want all other directories taken, too, you can specify that exactly: .PP .nf take,dironly,./var/vmail/* take,dironly,./var/vmail/*/* take,./var/vmail/*/*/.*.sieve ./var/vmail/** .fi .PP .PP .PP .nf mode:04:0 take,./etc/ ./** .fi .PP This would take all files from \fC/etc\fP, but ignoring the files that are not world-readable (\fCother-read\fP bit cleared); this way only 'public' files would get taken. .SH "Author" .PP Generated automatically by Doxygen for fsvs from the source code.