Re: git find (was: [RFC PATCH v3 8/8] --sparse for porcelains)

[Jakub Narebski <jnareb@gmail.com>]

On Tue, Aug 18, 2009, Nguyen Thai Ngoc Duy wrote:
> On Tue, Aug 18, 2009 at 1:25 PM, Jakub Narebski<jnareb@gmail.com> wrote:
> >
> > Well, I also think that it would be nice and useful to have "git find"
> > in addition to current "git grep".
> 
> Can you make a draft on how you want "git find" to be? Except the
> "-exec" part, Git allows us to search using various commands
> (ls-files, rev-list, log). I don't think a single "git find" can cover
> them all. I was thinking about putting more find-options to search
> commands we already have. ls-files would support -exec, for example.

Both git-rev-list and git-ls-files are plumbing, not porcelain.  Among
tools / commands you have mentioned only git-log is porcelain.

You need to process output of git-ls-files if you want to use more
complicated search criteria. 

> 
> A few things that I'd love to have supported:
>  - --depth for ls-files (probably all pathspec-as-argument commands)
>  - logical combination of search criteria
>  - unified blob locator. git-show understands SHA-1:/path/to/blob
> syntax. What if git-log can output using similar syntax, then feed
> them to git-grep in order to grep through (across commits)?

Draft specification for git-find.  git-find, like git-grep, searches
the filesystem dimension, and not time dimension like git-log.

git-find(1)
===========

NAME
----
git-find - Search for files in a repository

SYNOPSIS
--------
'git find' [--cached] [-z|--null] [(<tree> | <path>)...] [<expression>]

OPTIONS
-------
--cached::
        Instead of searching in the working tree files, check
        the blobs registered in the index file.

EXPRESSIONS
-----------
The expression is made up of options (which affect overall operation rather
than the processing of a specific file, and always return true), tests
(which return a true or false value), and actions (which have side effects
and return a true or false value), all separated by operators. `--and`  is
assumed where the operator is omitted.  If the expression contains no
actions other than `--prune`, `--print` is performed on all files for which
the expression is true.

OPTIONS
~~~~~~~
--max-depth <levels>::
        Descend  at  most levels (a non-negative integer) levels of 
        directories below the command line arguments.   `--max-depth 0`
        means only apply the tests and actions to the command line 
        arguments.

--min-depth <levels>::
        Do not apply any tests or actions at levels less than levels 
        (a non-negative integer).  `--min-depth 1` means process all
        files except the  command line arguments.

TESTS
~~~~~
--false::
        Always false.

--true::
        Always true.

--name <pattern>::
--iname <pattern>::
--path <pattern>::
--ipath <pattern>::
        [Entire] Filename matches glob.

--regex <expr>::
--iregex <expr>::
        Entire file name matches regular expression.

--lname <pattern>::
--ilname <pattern>::
        True if the file is a symbolic link whose contents match glob.

--size <n>[<unit>]::
        True if the file uses N units of space, rounding up.

--empty::
        File is empty and is either a regular file or a directory.

--type <C>::
        True if file is of type C: 'd' for directory, 'f' for regular
        file, 'l' for symbolic link, 's' for submodule, 'x' for 
        executable regular file (replaces `-perm` from 'find').

ACTIONS
~~~~~~~
(--exec | --ok) <command> ;
        Execute command; true if 0 status is returned.

(--execdir | --okdir) <command> ;
        Like `--exec`, but the specified command is run from the 
        subdirectory containing the matched file.

--print::
--print0::
--printf <format>::
--fprint <file>::
--fprint0 <file>::
--fprintf <file> <format>::
        True; print the full file name.

--prune::
        True; if the file is a directory, do not descend into it.

--quit::
        Exit immediately.


OPERATORS
~~~~~~~~~
--and::
--or::
--not::
( ... )::
        Specify how multiple expressions are combined using Boolean
        expressions.  `--and` is the default operator.

-- 
Jakub Narebski
Poland