1 '\" te
   2 .\"  Copyright (c) 1996 Sun Microsystems, Inc.  All Rights Reserved.
   3 .\"  Copyright 2015 Nexenta Systems, Inc. All rights reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH PACKINGRULES 4 "Sep 8, 2015"
   8 .SH NAME
   9 packingrules \- packing rules file for filesync
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB$\fR\fBHOME\fR\fB/.packingrules\fR
  14 .fi
  15 
  16 .SH DESCRIPTION
  17 .LP
  18 \fB$\fR\fBHOME\fR\fB/.packingrules\fR is a packing rules file for
  19 \fBfilesync\fR. \fB$\fR\fBHOME\fR\fB/.packingrules\fR
  20 contains a list of directories and files that are to be packed and
  21 synchronized.  It also contains a list of directories and files that  are to be
  22 specifically excluded from packing and synchronization. See  \fBfilesync\fR(1).
  23 .LP
  24 The \fB$\fR\fBHOME\fR\fB/.packingrules\fR file is automatically created if
  25 users invoke \fBfilesync\fR with filename arguments. By using \fBfilesync\fR
  26 options, users can augment the packing rules in
  27 \fB$\fR\fBHOME\fR\fB/.packingrules\fR.
  28 .LP
  29 Many users choose to manually create the packing rules file and edit it by
  30 hand. Users can edit \fB$\fR\fBHOME\fR\fB/.packingrules\fR (using any editor)
  31 to permanently change the \fB$\fR\fBHOME\fR\fB/.packingrules\fR file, or to
  32 gain access to more powerful options that are not available from the command
  33 line (such as \fBIGNORE\fR commands). It is much easier to enter complex
  34 wildcard expressions by editing the \fB$\fR\fBHOME\fR\fB/.packingrules\fR file.
  35 .LP
  36 Blank lines and lines that begin with a pound sign  (`\fB#\fR') are ignored.
  37 .LP
  38 Any line can be continued by placing a backslash  (`\fB\e\fR\&') immediately
  39 before the  \fBNEWLINE.\fR
  40 .LP
  41 All other lines in the  \fB$\fR\fBHOME\fR\fB/.packingrules\fR file have one of
  42 the following formats:
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fBPACKINGRULES\fR\fR
  47 .ad
  48 .sp .6
  49 .RS 4n
  50 \fImajor\fR. \fIminor\fR. This line is not actually required, but it should be
  51 the first  line of every packing rules file. This line identifies the packing
  52 rules file for the  \fBfile\fR(1) command and specifies a format version
  53 number. The current version number is 1.1. See \fBfile\fR(1).
  54 .RE
  55 
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fBBASE\fR \fIdirectory-1\fR [\fIdirectory-2\fR]\fR
  60 .ad
  61 .sp .6
  62 .RS 4n
  63 This line identifies a directory (or pair of directories) under which files
  64 should be packed and synchronized. At least one directory name must be
  65 specified. For rules that are to be used by \fBfilesync\fR a second directory
  66 name (where the copies are to be kept) must also be specified. The arguments
  67 must be fully qualified path names, and may include environment variables.
  68 .RE
  69 
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBLIST\fR \fIname\fR \|.\|.\|.\fR
  74 .ad
  75 .sp .6
  76 .RS 4n
  77 This line enumerates a list of files and sub-directories  (beneath the current
  78 \fBBASE)\fR that are to be kept  synchronized. This specification is recursive,
  79 in that specifying the name of a directory automatically includes all files and
  80 subdirectories it contains. Regular expressions  (as described in \fBglob\fR
  81 and \fBgmatch\fR) are permitted. See \fBglob\fR(1) and  \fBgmatch\fR(3GEN).
  82 .RE
  83 
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBIGNORE\fR \fIname\fR \|.\|.\|.\fR
  88 .ad
  89 .sp .6
  90 .RS 4n
  91 This line enumerates a list of files that are not to be kept synchronized.
  92 Regular expressions  (using \fBglob\fR  and \fBgmatch\fR) are permitted.
  93 .RE
  94 
  95 .sp
  96 .LP
  97 There are important differences between the arguments to \fBLIST\fR and
  98 \fBIGNORE\fR statements. The arguments to a \fBLIST\fR statement can contain
  99 slashes and are interpreted as file names relative to the  \fBBASE\fR
 100 directories. The arguments to an \fBIGNORE\fR statement are simpler names or
 101 expressions that cannot contain slashes. An \fBIGNORE\fR statement will not
 102 override a \fBLIST\fR statement. \fBIGNORE\fR statements only exclude files
 103 that are found beneath \fBLISTed\fR directories.
 104 .sp
 105 .LP
 106 If the first name argument to a  \fBLIST\fR statement begins with an
 107 exclamation point  (`\fB!\fR'), the remainder of the statement will be executed
 108 as a command. The command will be run in the current \fBBASE\fR directory. The
 109 output of the command will be treated as a  list of newline separated file
 110 names to be packed/synchronized. The resulting file names will be interpreted
 111 relative to the enclosing  \fBBASE\fR directory.
 112 .sp
 113 .LP
 114 If the first name argument to an  \fBIGNORE\fR statement begins with an
 115 exclamation point  (`\fB!\fR'), the remainder of the statement will be executed
 116 as a command. The command will be run in the current \fBBASE\fR directory. The
 117 command will be expected to figure out which names should not be synchronized.
 118 The output of the command will be treated as a list of newline separated file
 119 names that should be excluded from the packing and synchronization list.
 120 .sp
 121 .LP
 122 Commands will be broken into distinct arguments and run directly with  \fBsh
 123 \fR\fB-c\fR. Blanks can be embedded in an argument by escaping them with a
 124 backslash (`\fB\e\fR\&') or enclosing the argument in  double quotes (`
 125 \fB"\fR '). Double quotes can be passed in arguments by escaping the double quotes with
 126 a backslash (`\fB\e\fR\&').
 127 .sp
 128 .LP
 129 \fBLIST\fR lines only apply to the  \fBBASE\fR statement that precedes them.
 130 \fBIGNORE\fR lines can appear before any  \fBBASE\fR statement (in which case
 131 they apply to all \fBBASEs)\fR or after a  \fBBASE\fR statement (in which case
 132 they only apply to the  \fBBASE\fR that precedes them). Any number of  these
 133 statements can occur in any combination. The order is not important.
 134 .SH EXAMPLES
 135 .LP
 136 \fBExample 1 \fRA sample \fB$\fR\fBHOME\fR\fB\&.packingrules\fR file.
 137 .sp
 138 .LP
 139 The use of these statements is illustrated in the following
 140 \fB$\fR\fBHOME\fR\fB\&.packingrules\fR file.
 141 
 142 .sp
 143 .in +2
 144 .nf
 145 #
 146 # junk files, not worth copying
 147 #
 148 IGNORE core *.o *.bak *%
 149 #
 150 # most of the stuff I want to keep in sync is in my $HOME
 151 #
 152 BASE /net/bigserver/export/home/myname $HOME
 153 # everything in my work sub-directory should be maintained
 154 LIST work
 155 # a few of my favorite mail boxes should be replicated
 156 LIST m/incoming
 157 LIST m/action
 158 LIST m/pending
 159 #
 160 # I like to carry around a couple of project directories
 161 # but skip all the postscript output
 162 #
 163 BASE /net/bigserver/export/projects $HOME/projects
 164 LIST poindexter epiphany
 165 IGNORE *.ps
 166 #
 167 # the foonly package should always be kept on every machine
 168 #
 169 BASE /net/bigserver/opt/foonly /opt/foonly
 170 LIST !cat .packinglist
 171 #
 172 # and the latest executables for the standard build environment
 173 #
 174 BASE /net/bigserver/export/buildenv $HOME/buildenv
 175 LIST !find . -type f -a -perm -111 -a -print
 176 .fi
 177 .in -2
 178 .sp
 179 
 180 .SH SEE ALSO
 181 .LP
 182 \fBfile\fR(1), \fBfilesync\fR(1)