SFK: help select (Help)

Команда: help select
sfk file selection reference:

   default principles of most sfk commands:

      - subdirectory (subfolder) processing is done by default.
      - filename comparison is case insensitive.
      - hidden and system files are not processed,
        except for some commands like copy.
      - symbolic links are followed.

        type "sfk help options" on how to change that.

   how to select directories and contained filenames:

   sfk provides many ways of specifying which files you want to process,
   from very simple but unflexible to very detailed.

   1. short format file selection:

      dirname [filemask1] [filemask2] [!fileexcludemask] [...]

      this format supports ONE directory name, followed by many file masks.
      it can be used with most commands processing directory trees.

      example:

      sfk list mydir foo bar .txt .zip !-tmp
         selects all files
         - in directory mydir and all its subdirectories
         - having foo OR bar in their filename (no * required)
         - OR which are ending with .txt OR .zip (no *.txt required)
         - but not having -tmp in their filename

      supported by commands:
         list, select, stat, run, detab, scantab, hexdump and some more.

   2. long format file selection:

      -dir root1 [root2] [*pathmask*] [...] [-file mask1 [mask2] [...]
         [-dir root3 root4 !direxcludemask -file mask3 !xmask4] [...]

      this format supports

      - several root directory sets, starting with -dir, each of them
        containing many directories, path masks or dir exclusion masks.
        a path mask is an expression in a directory set containing a
        wildcard character "*". a dir exclusion mask is started
        by ! and may be surrounded by \ to select exact dir names.

      - a file mask set per root directory set, starting with -file.
        this may also contain file exclusions starting with !

      supported by:
         nearly every command than can process file sets.

      to select all dirs of current dir except something:
      -dir . !foo       -> exclude subdirs like *foo*
      -dir . !.foo      -> exclude with extension .foo
      -dir . !\foo      -> exclude starting with foo
      -dir . !foo\      -> exclude ending with foo
      -dir . !\foo\     -> exclude exactly foo
      -dir . !\foo\bar\ -> exclude subdir combi
      -dir . !*.foo*    -> exclude with .foo anywhere

      to select only sub dirs of current dir with something:

      using wide sub dir expressions:
      -dir . -subdir foo       -> include paths having *foo*
      -dir . -subdir \foo      -> include paths having *\foo
      -dir . -subdir foo\      -> include paths having *foo
      -dir . -subdir \foo\     -> include paths exactly foo
      -dir . -subdir .foo      -> include with extension .foo
      -dir . -subdir \foo\bar\ -> include subdir combi
      instead of -subdir, you may also type just -sub

      using compact sub dir expressions:
      -dir . *foo*      -> include paths having *foo*
      -dir . *\foo      -> include paths having \foo
      -dir . *foo\      -> include paths having foo\
      -dir . *\foo\     -> include paths exactly foo
      -dir . *.foo      -> include with extension .foo
      -dir . *\foo\bar\ -> include subdir combi

      exclusion by filename:
      -file !foo        -> exclude all files like *foo*
      -file !\foo       -> exclude starting with foo
      -file !foo\       -> exclude ending with foo
      -file !\foo\      -> exclude exactly foo
      -file !.foo       -> exclude extension foo

      inclusion by filename:
      -file foo         -> include all files like *foo*
      -file \foo        -> include starting with foo
      -file foo\        -> include ending with foo
      -file \foo\       -> include exactly foo
      -file .foo .bar   -> select .foo and .bar files

      examples

      sfk scantab -dir mydir1 mydir2 *include* -file foo bar .hpp
         scans all files for TAB characters
         - in directory mydir1 and all its subdirectories
           AND
         - in directory mydir2 and all its subdirectories
           IF
           - 1. the file path contains the word "include",
             e.g. mydir1\core\include\foosys.hpp
           - 2. the filename contains foo OR bar
           - 3. or the filename ends with .hpp

      sfk scantab -dir mydir1 !include -file !.tmp !.save
         scans all files for TAB characters in folder mydir1,
         excluding all sub dirs having "include" in their name,
         and excluding all .tmp and .save files.

      sfk list -dir source include -subdir save !.svn -file .bak
         list .bak files from directory trees source and include,
         within in sub directories having "save" in their name,
         excluding sub directories ending with ".svn".

      sfk list -dir source include *save !.svn -file .bak
         the same as above, written in compact subdir format:
         subdir inclusion masks require a wildcard * anywhere
         to make it clear they're no root directories.
         subdir exclusion masks can stay as they are.

      file set reuse within scripts:

      to allow reuse of the same -dir ... -file ...
      parameters by different commands, these options exist:

      -root x     prefix every -dir parameter by x,
                  then remove x in the -dir parameters to
                  make a fileset compatible to copy/sync
      -using l    use -dir ... -file ... text given at label l.
                  text in that label may contain // remarks,
                  but no variables like #(foo).
      -checkdirs  stop if given -dir folders do not exist

      to get a full example script type:

         sfk batch mytest.bat    for a Windows .bat example
         sfk batch mytest.sh     for a Cygwin/Linux .sh example

   3. single parameter file set selection:

      some commands like find, filter or tail do not accept the full
      short format, but only a single file or dir parameter, as it
      would get too complicated mixing the short format with local
      options. find more on that in the command's local help.

   4. passing filename lists in command chains:

      instead of selecting files in the current command, you may use
      a filename list created by a previous command, for example:

      sfk select mydir .txt +detab=3
         selects all .txt files from directory mydir, then passes
         this file list to detab, where the files are detabbed.

      command chaining is more intuitive, as you can play around
      with different file sets before executing actual changes
      on the selected files.

      sfk filter names.txt +texttofilenames +list -late
         provided that names.txt contains a list of filenames,
         this command chain lists the most recent of these files.
         note that in this case, it is unclear if to pass
         - the filename "names.txt" or
         - the line contents from within names.txt
         as filenames to "list", therefore we need to insert
         +texttofilenames or +ttf to enforce a conversion.

      supported by:
         some commands. check each command's local help for more.

   see also
      sfk help options  general options for most commands.
      sfk list          for more file selection examples.