Package: ff-find
Easily search and process files.If you need to search files by their contents,orsearch for their
contents, please look atackorpss. These are better suited for
this kind of task.Current stable version1.0.5Whyffand notfind?Just because I find that most of my searches was:find . -iname '*name*'And it’s easier to me to enter:ff nameAlso, myfindhave sometimes problems with non ascii names:% find /tmp -name '*GÖS*'
%And withff:% ff '*GÖS*' /tmp
/tmp/eee_GÖS_från_förstår_pas
/tmp/eee_GÖS_från_pas_förstår_qq
/tmp/pas_GÖS_från_förstår
%it just works! :)Basic usageff passwdSearch for all files and directories in current directory and below,
which is match to pattern:*passwd*.ff -B passwdSearch for all files and directories in current directory and below,
which is match to pattern:*passwd.ff -E passwdSearch for all files and directories in current directory and below,
which is match to pattern:passwd*.ff -EB passwdAdvanced usageff -p pa -s /tmp --shell-exec -x '[ -f "{path}" ] && mkdir -p /tmp{dirname}; cp -r "{path}" "/tmp{path}"'Find all files and directories in /tmp that match expression:*pa*,
and copy them (with original directories hierarchy!) to /tmp.So powerful!Magic patternIt’s form of pattern known good for Perl or AWK lovers :)If patterns is in general form:mode/pattern/modifier(decribed more in full usage below), then it is parsed and used in a
little other manner.Instead of arguments--regexpor--fuzzy, you can pass it inmodepart of pattern. Next there is delimiter, which usually is/(backslash), but there can be more characters, described in Usage
section.After that is a pattern, next delimiter again, and then modifiers
(again, modifiers are described in Usage section).Some examples:Search for all files and directories in current directory and below,
which is match to pattern:passwd.ff f/pwd/Search for all files and directories in current directory and below,
which name contains letters ‘p’, ‘w’, ‘d’, with any other characters
between them.ff g/^(chk)?passwd/Search for all files and directories in current directory and below,
which name starts from ‘chkpasswd’ or ‘passwd’.Configuration fileffrecognizes 2 configuration files: user-wide and project-wide.
Both can specify the same things and have identical syntax (ini files).
User-wide one is located in$HOME/.ff.rc, and project-wide is
located in current directory (ie. projects root). Example file is
located at (github)[https://github.com/mysz/ff/blob/master/ff.rc].PluginsPlugins are the way to easily extend capabilities offf. Currently
there is only support for plugins allowing to extend tests made on files
list. In future, there is plan to add support for plugins allowing to
make some actions on found files (currently isbuilt-in plugin:--shell), for example modifying, copying or anything else).ffsearch for plugins in user’s home directory, but there is
posibility to tell him about the other.. By default,ffsearch for
plugins in:~/.ff/pluginsAnd using switch--plugins-pathyou can tellffabout other
plugins location.You can also pass argument to plugins. For example, insizeplugin
(bundled withff), You must to tell the plugin what size of file You
expect:`ff pas --test size:=5k`Above example will find every file withpaspart in its name, and its
size isexactly5kibibytes.
More aboutsizeplugin inprojects
wiki.Writing pluginsPlugins are written inPython, and are simple
Python modules with at leastplugin_actioncallable specified.
Plugins are imported, andplugin_actionmust returnTrueorFalseto tellffthat given found object meets expectations, and
should be returned.ffrecognize and use only 3 objects in plugin:plugin_action- (REQUIRED) [callable] must returnTrueodFalse. Must recognize 3 arguments:name- name of pluginargument- argument passed by userpath- absolute path to tested objectPLUGIN_DESCR- (OPTIONAL) [string or callable] short descr of
plugin, printed whenffis called with switch--help-test-pluginsPLUGIN_HELP- (OPTIONAL) [string or callable] full help for
plugin, printed whenffis called with switch--help-test-pluginsTEST_NAMEPlugin file also must have special name, and be placed in directory
recognized byff(see: [plugins][plugins]). Name of file is built
with three parts, connected with underscore: *ffplugin- fixed
prefix *test- type of plugin (currently onlytestplugins are
recignized) *NAME- name of pluginAnd as Python module, must and with.pyextension :)Plugin must validate input data (argument), and raiseFFPluginErrorexception with approbiate message on any error. Plugin
shouldn’t raise any other exceptions. There is one caveat with this:FFPluginErrorexception is declaredinsideff! When given
plugin is imported, it ismonkeypatchedandFFPluginErrorexception is injected into it.There is an example plugin, which allow us to search for files in
specified size. Is inproject
repositoryin
directory plugins. You can use it as a base for your own plugins :)Installationffshould work on any platform wherePythonis available, it means Linux, Windows, MacOS X etc. There is no
dependencies, plain Python power :)To install, you can usepip:pip install ffVoila!Usageusage: ff [-h] [--print0] [--ignorecase] [--source source] [--pattern PATTERN]
          [--regexp] [--fuzzy] [--depth DEPTH] [--path-search]
          [--regex-multiline] [--regex-dotall] [--begin] [--end]
          [--invert-match] [--mode MODE] [--exec COMMAND] [--prefix]
          [--prefix-dirs PREFIX_DIRS] [--prefix-files PREFIX_FILES]
          [--no-display] [--no-colorize] [--verbose-exec] [--interactive-exec]
          [--shell-exec] [--vcs] [--exclude-path EXCLUDED_PATH] [--test TESTS]
          [--plugins-path PLUGINS_PATH] [--version]
          [--help-test-plugins [TEST_NAME[,TEST2_NAME]]]
          [--show-plugins-paths]
          [pattern] [source [source ...]]

Easily search and process files.

positional arguments:
  pattern               pattern to search
  source                optional source (if missing, use current directory)

optional arguments:
  -h, --help            show this help message and exit
  --print0, -0          split results by binary zero instead of new line
                        (useful to work with xargs)
  --ignorecase, -i, --ignore-case
                        ignore case when match pattern to paths
  --source source, -s source
                        optional, see: source above
  --pattern PATTERN, -p PATTERN
                        optional, see: pattern above
  --regexp, -g          treat pattern as regular expression (uses Python
                        regexp engine)
  --fuzzy, -f           pattern defines only set and order of characters used
                        in filename
  --depth DEPTH, -D DEPTH
                        how deep we should search (default: -1, means
                        infinite)
  --path-search, -q     search in full path, instead of bare name of item
  --regex-multiline, -l
                        modify meta characters: "^" and "$" behaviour when
                        pattern is regular expression. See:
                        http://docs.python.org/2/library/re.html#re.MULTILINE
  --regex-dotall, -d    modify meta character: "." behaviour when pattern is
                        regular expression. See:
                        http://docs.python.org/2/library/re.html#re.DOTALL
  --begin, -B           match pattern to begin of item name (ignored in regexp
                        mode)
  --end, -E             match pattern to end of item name (ignored in regexp
                        mode)
  --invert-match, -v, -r
                        find objects that do *not* match pattern
  --mode MODE, -m MODE  allow to choose to search for "files" only, "dirs", or
                        "all"
  --exec COMMAND, -x COMMAND
                        execute some command on every found item. In command,
                        placeholders: {path}, {dirname}, {basename} are
                        replaced with correct value
  --prefix              add prefix "dr: " (directory) or "fl: " (file) to
                        every found item
  --prefix-dirs PREFIX_DIRS
                        prefix for matched directories
  --prefix-files PREFIX_FILES
                        prefix for matched files
  --no-display          don't display element (useful with --exec argument)
  --no-colorize         Colorize output
  --verbose-exec        show command before execute it
  --interactive-exec    ask before execute command on every item
  --shell-exec          execute command from --exec argument in shell (with
                        shell expansion etc)
  --vcs                 do not skip VCS directories (.git, .svn etc)
  --exclude-path EXCLUDED_PATH, -c EXCLUDED_PATH
                        skip given paths from scanning
  --test TESTS, -t TESTS
                        additional tests, available by plugins (see
                        annotations below or --help-test-plugins)
  --plugins-path PLUGINS_PATH
                        additional path where to search plugins (see
                        annotations below)
  --version             show program's version number and exit
  --help-test-plugins [TEST_NAME[,TEST2_NAME]]
                        display help for installed test plugins
  --show-plugins-paths  Show recognized plugins paths and exit

Pattern, provided as positional argument (not with --pattern) can be provided
in special form (called: magic pattern). It allows to more "nerdish"
(or "perlish" :) ) way to control `ff` behavior.

The general pattern for magic pattern is:

    mode/pattern/modifier

where:
    mode - is one of 'p' (--pattern), 'g' - (--regexp) or 'f' (--fuzzy)
    / - is delimiter:
        * one of: '/', '!', '@', '#', '%', '|', and then start and end
            delimiter must be the same
        * one of: '{', '[', '(', '<', and the end delimiter must be the
            closing one (ex. '}' if start is '{')
    pattern - any pattern, processed in a way specified with 'mode'
    modifier - one of: 'i' (--ignore-case), 'm' (--regex-multiline),
        's' (--regex-dotall), 'v' (not used currently), 'r' (--invert-match)

There is also ability to extend capabilities of `ff` by plugins. Plugins are
run with switch --test and then plugin name with optional plugin argument:

    --test plugin_name:plugin_arg

There can be used more then one plugin at once.

Authors:
    Marcin Sztolcman <marcin@urzenia.net> // http://urzenia.net

HomePage:
    http://mysz.github.io/ff/AuthorsMarcin Sztolcmanmarcin@urzenia.netContactIf you like or dislike this software, please do not hesitate to tell me
about this me via email (marcin@urzenia.net).If you find bug or have an idea to enhance this tool, please use
GitHub’sissues.LicenseThe MIT License (MIT)Copyright (c) 2013 Marcin SztolcmanPermission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
“Software”), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.ChangeLogv1.0.5use README.rst for Pypiv1.0.4fixes for Pypiv1.0.3fixes for Pypiv1.0.2fixes for Pypiv1.0.1fixes for Pypiv1.0.0backward incompatible: magic pattern doesn’t recognize ‘q’ flag for
‘path-search’ mode, flag –path-search must be passed explicitlynew option: –depth - limit searching to this depthnew option: –colorizenew: parse and recognize configuration filesnew: added ability to install via pipchanged versioning format: useSemVercode cleanups and many refactorizations/rewritespaths are now normalized before comparisons of excluded pathsparse regexps with UNICODE flag‘?’ and ‘+’ are now valid delimiters in magic patternignore case of –mode optiondocumentation improvementsmore testsimproved fuzzy searchbetter validation of argumentsimproved error messagesimproved helpbetter interoperability: do not hardcode new line characters or path
delimitersdo not allow for duplicating modifiersFIX: do not crash on unknown characters, just replace themFIX: do not crash on printing unknown charactersadded simple Makefileimproved config for pylintadded config forversionnerv0.5ability to run plugins for tests (with first plugin: size)many improvements to proper handling UTF-8many improvements for work in Python3improved PEP8 compatibilityrefactored codeadded –version switchremoved expanding shell variables when execute external command if no
–shell-exec is givenv.0.4added changelogadded fuzzy-search modeadded ‘magic pattern’ mode-r argument is now an alias to -vbetter handling unicode characters in pathshandling CTRL-Cadded modifier: –path-searchv0.3use argparse instead of getopt to parse optionsallow to exclude path from searchimproved help and documentationv0.2added option ‘shell-exec’ - allow to exec programs with shell
expansionexec: add shell variables expansionby default, skip VCS directoriesadded option ‘print0’ - delimit entries with binary 0, as for xargsadded options ‘interactive-exec’ - ask before every execmuch more powerfull exec engineadded option ‘no-display’ - do not display results (useful with
–exec)added option ‘verbose-exec’ - show executed commandadded option ‘invert-match’ - like in grepimproved help and documentationcleanups in codev0.1initial version