home | help 
XSTOW.INI(5)		      XStow Reference Guide		    XSTOW.INI(5)

NAME
     xstow.ini, config file for XStow

CONTENT
     The  xstow.ini  file  contains  some static informations about your system.
     It's possible setting most necessary values by setting the required command
     line option, but in some cases this won't make sense if you are using xstow
     quite often.

SYNTAX
     The syntax of the configuration file is simple. It's the same as it is used
     by KDE and GNOME.

     The data is splitted into keys values and sections. The '#'  sign	marks  a
     comment. Here is an example:

	     [traverse-links]
	     keep-targets = true
	     link = /usr/tmp  # comment

     [traverse-links]
	 is a section with the name "traverse-links"

     keep-targets = true
	 is  a	key  - value pair, where 'keep-targets' is the key and 'true' is
	 the value.

PROCESSING
     XStow processes the config files one after  another.  Static  configuration
     options like the [debug]=>module option can be overwritten by the next con-
     fig  file.  List  keys  like [traverse-links]=>link will be appended to the
     list.

     If you wan't more informations about the current stow setup call XStow like
     this:

	     xstow -s -dl 1 dummy-package | less

     For getting information about which config files were  processed  you  will
     have to set some environment values (see xstow(1) for details).  Eg.:

	     XSTOW_DEBUG_LEVEL=1 xstow -s -dl 1 dummy-package | less

DESCRIPTION
   SECTION traverse-links
     In  this section a number of links are listed, which xstow will identify as
     links that are not part of an xstow managed package.  Eg.:  For  conforming
     to  the  FHS  it  is common setting a link from /usr/share/man to /usr/man.
     This  will  cause	old   applications   installing   theire   manpages   in
     /usr/share/man, rather than in /usr/man.

     But xstow is paranoid and believes that the link contains to something else
     and it is not allowed writing data into the directory the link points to.

     The  simple solution is telling xstow which links should be handled as nor-
     mal directories. These links can be listed in this section.

     link = LINK
	 The value of this key must contain an absolute path to  the  link  that
	 should  be handled as a normal directory. The link itself can be an ab-
	 solute, or relativ link.  It is allowed that there are  more  than  one
	 link keys in this section.

     keep-targets = BOOL
	 Allowed values are 'true' and '1' (incasesensitive). Anything else will
	 be  interpreted as false.  If keep-targets is set to true the target of
	 the links in this section will automatically  added  to  the  keep-dirs
	 section.  This  avoids that these targets will be removed and the links
	 will become dead links.

     add-if-target = PATTERN
	 Automatic add all links which targets match the  pattern  to  the  link
	 list.	XStow will use this as the last chance for solving dependencies.
	 Only if all other tests failed the application will  try  appling  this
	 test.	This means that it is no problem setting [links]=>absolute-links
	 to true and using a pattern like /* here.  If keep-targets  is  set  to
	 true the applied links will added to the keep-dirs list too.

     add-if-target-regex = REGEX
	 Does  the same as add-if-target, but support regular expressions. XStow
	 will always try matching the  regular	expressions  before  the  normal
	 shell	patterns, cause a regex can be much more exact than a shell pat-
	 tern.

   SECTION keep-dirs
     In this section directories are listed that should not be remove. When  xs-
     tow  removes  a  package and a directory becomes emty the directory will be
     removed too.

     dir = DIR
	 The value of this key must contain an absolute path  to  the  directory
	 that  should  be  kept.  It is allowed that there are more than one dir
	 keys in this section. The value should not end with a '/'!!

   SECTION matches
     XStow will try matching this pattern to all file names that were  found  in
     packages.	Only  the  file  names.  So  you  do  not have to care about the
     slashes.

     ignore = PATTERN
	 Ignore files matching this pattern.  It is allowed that there are  more
	 than one ignore keys in this section.

     ignore-regex = REGEX
	 Does  the  same  as ignore, but support regular expressions. XStow will
	 always try matching the regular expressions  before  the  normal  shell
	 patterns, cause a regex can be much more exact than a shell pattern.

     copy = PATTERN
	 Copy  files or directories matching this pattern instead of linking it.
	 This makes sense in case of some global files that will be used by more
	 than one package and will be updated in the course of the  installation
	 process. Files that were installed this way won't be removed in case of
	 unstowing  a  package,  since XStow can not handle package dependencies
	 and does not know if any other package requires the file.  If a  direc-
	 tory  matches	this  expression  the  content	of the directory will be
	 copied recoursively. This can be useful in case of some /etc files, in-
	 stalled by the installation process.  It is allowed that there are more
	 than one copy keys in this section.

     copy-regex = REGEX
	 Does the same as copy, but support regular expressions. XStow will  al-
	 ways  try matching the regular expressions before the normal shell pat-
	 terns, cause a regex can be much more exact than a shell pattern.

     nignore = NIGNORE_RULE
	 Ignore everything except file and directories matching this expression.
	 eg: "systree/bintree".  For using nignore support fnmatch and configra-
	 tion file support has to be enabled.  A rule (eg.: "systree/headertree"
	 ) has a set of subrules (eg.: "systree" and "headertree" ).  These sub-
	 rules are defined in a separate section which is named as the	subrule.
	 Eg, the subrule for "systree":

		 [systree]
		 dir	   = /usr
		 dir	   = /usr/local
		 follow    = false

	 There	is  an example config file "nignore.ini" in the doc directory of
	 this package.

   SECTION NIGNORE-SUB-RULE
     Description of a nignore subrule. This section is called like  the  nignore
     subrule, eg: "systree".

     dir = DIR
	 Directories  where  a	file of the package should be installed. You can
	 use shell pattern's too (eg.: "/man/man*"), but use this  feature  only
	 if this subrule is the last one in an nignore rule.

     follow = BOOL
	 Follow subdirs.

   SECTION stow-dirs
     dir = DIR
	 The  value  of  this key must contain an absolute path to the directory
	 that can be handled as it would be part  of  the  own	stow  directory.
	 This  means  xstow  is allowed to make changes in packages that are re-
	 lated to this directory.  It is allowed that there are  more  than  one
	 dir keys in this section. The value should not end with a '/'!!

     auto-add-dirs = PATTERN
	 Automatically	add  a directory if it matches this pattern. In Stow di-
	 rectories, which  were  detected  with  this  pattern,  never	will  be
	 searched  for	configuration  files.  It is allowed that there are more
	 than one auto-add-dirs keys in this section.

     auto-add-dirs-regex = REGEX
	 Does the same as auto-add-dirs, but support regular expressions.  XStow
	 will  always  try  matching  the  regular expressions before the normal
	 shell patterns, cause a regex can be much more exact than a shell  pat-
	 tern.

   SECTION protect-dirs
     The  goal	of this section is limiting the access within a legal target di-
     rectory. Eg.: If your stow directory is '/stow' and you installing packages
     this way:

	     make install DESTDIR=/stow/package_name

     But the 'prefix' is set to '/usr/local'. In this case target directory will
     be '/', but the real target directory of package will be '/usr/local'.  The
     following	keys  withing this section allowing to restrict the installation
     access within the valid target directory.

     dir = DIR
	 The value of this key must contain an absolute path  to  the  directory
	 that  has  not  be  changed.  XStow is not allowed installing a package
	 there and withing the subdirectories, and will report an error,  if  it
	 would. It is allowed that there are more than one dir keys in this sec-
	 tion. The value should not end with a '/'!!

     auto-add-dirs = PATTERN
	 Automatically	add  a	directory if it matches this pattern.  It is al-
	 lowed that there are more than one auto-add-dirs keys in this section.

     auto-add-dirs-regex = REGEX
	 Does the same as auto-add-dirs, but support regular expressions.  XStow
	 will  always  try  matching  the  regular expressions before the normal
	 shell patterns, cause a regex can be much more exact than a shell  pat-
	 tern.

     target = DIR
	 The  value  of  this key must contain an absolute path to the directory
	 that is allowed to be changed. If this value is set, XStow will  report
	 an  error  if	it  would touch any other, or upper directory within the
	 tree.	It is allowed that there are more than one target keys	in  this
	 section. The value should not end with a '/'!!

     target-add-traversable-links = BOOL
	 Automatically add the targets of traversable links to the targets list.
	 This  can  be useful if you do not add manually all possible targets of
	 traversable links to the target list. By default this value is  set  to
	 false.

     If  your  stow directory is '/stow' and all packages should be installed in
     '/usr/local/' such a config file will make sense:

	     [traverse-links]
	     link = /usr/local/etc

	     [protect-dirs]
	     target = /usr/local
	     target-add-traversable-links = true

     XStow will report an error  if  it  would	install  a  package  outside  of
     '/usr/local'

   SECTION debug
     These  values will be ignored if one of these values is set by command line
     option.

     module = MODULE
	 Set the default debug module.

     level = INTEGER
	 Set the debug level.

   SECTION config-files
     in-home = BOOL
	 Search in home directory for a config file named "xstow.ini"  or  ".xs-
	 tow.ini". Only in the home directory will be searched for hidden files.

     in-stow-dir = BOOL
	 Search in current stow directory for a config file

     in-other-stow-dirs = BOOL
	 Search in other public stow directories for config files.

     file = FILE
	 Read this config file too.

	 It is allowed that there are more than one file keys in this section.

   SECTION links
     absolute-paths = BOOL
	 Create links with absolute path names.

   SECTION exec
     If  a package comes with some GNU info files, install-info creates an index
     directory named 'dir' in STOWDIR/PACKAGE/share/info. If this is  the  first
     package with an info index file this won't be a problem.

     If  a second package creates another 'dir' file in the packages info direc-
     tory, this file will not contain the informations from  the  first  package
     too  and  xstow will report a problem unless you use the ignore or copy op-
     tion.

     But using the copy option is not a solution since the content  of	each  of
     the  files  is incomplete.  You can use the ignore option and run mkinfodir
     in the /usr/local/info directory after installing the package  with  xstow.
     (Such a script is available on various distributions.)

     The  other  solution  is  running a program that merges the old and the new
     'dir' file.  This section provides a hook, that allows executing such tools
     if a file or directory matches a condition.

     XStow shippes a programm called merge-info(1) that can be used this way.

     There can be more than one exec Section within an ini file!

     match = PATTERN
     exec = COMMAND
	 Executes the command if a file matches the match expression. %t is  re-
	 places by the target file and %s is replaced by the source file.

     exec-unstow = COMMAND
	 Executes the command if a file matches the match expression and a pack-
	 ages  is  unstowed. If exec-unstow is not set and a package will be un-
	 stowed, nothing will be executed.  %t is replaces by  the  target  file
	 and %s is replaced by the source file.

EXAMPLE xstow.ini
   EXAMPLE 1
     Here  is  an  example xstow.ini which is common for a system where xstow is
     managing the /usr/local tree.

	     [traverse-links]
	     keep-targets = true
	     link = /usr/local/tmp
	     link = /usr/local/var
	     link = /usr/local/man
	     link = /usr/local/doc
	     link = /usr/local/info

	     [keep-dirs]
	     dir = /usr/local/bin
	     dir = /usr/local/sbin
	     dir = /usr/local/lib
	     dir = /usr/local/include

	     [matches]
	     ignore = *~
	     ignore = core
	     ignore = core.*
	     ignore = CVS

	     [exec]
	     match = dir # GNU info index file
	     exec = merge-info %t %s -o %t
	     exec-unstow = merge-info -u %t %s -o %t

	     [stow-dirs]
	     dir = /usr/local/stow
	     dir = /usr/local/stow2

   EXAMPLE 2
     This is an example xstow.ini for a  system  where	xstow  is  managing  the
     '/usr/local' tree, but the stow directory is '/stow'.

	     [matches]
	     ignore = *~
	     ignore = CVS
	     ignore = core*

	     [stow-dirs]
	     dir = /stow

	     [protect-dirs]
	     target = /usr/local

SEE ALSO
     xstow(1) merge-info(1) xstow.ini file.

XStow 1.1.0			   2022-07-25			    XSTOW.INI(5)
home | help