Provided by: git-annex_10.20230626-1_amd64 bug

NAME

       git-annex-matching-options - specifying what to act on

DESCRIPTION

       Many  git-annex  commands  support using these options to specify which files they act on.
       Some of these options can also be used by commands to specify which keys they act on.

       Arbitrarily complicated expressions can be built using these options.  For example:

        --include='*.mp3' --and -( --in=usbdrive --or --in=archive -)

       The above example makes git-annex work on only mp3 files that are present in either of two
       repositories.

OPTIONS

       --exclude=glob

              Skips  files matching the glob pattern. The glob is matched relative to the current
              directory. For example:

               git annex get --exclude='*.mp3' --exclude='subdir/*'

              Note that this will not match anything when using --all or --unused.

       --include=glob
              Skips files not matching  the  glob  pattern.   (Same  as  --not  --exclude.)   For
              example, to include only mp3 and ogg files:

               git annex get --include='*.mp3' --or --include='*.ogg'

              Note that this will not skip anything when using --all or --unused.

       --excludesamecontent=glob
              Skips  a  file when there is another file with the same content, whose name matches
              the glob. The glob is matched relative to the current directory.

              For example, to drop files in the archive directory, but not when the same  content
              is used by a file in the work directory:

               git annex drop archive/ --excludesamecontent='work/*'

       --includesamecontent=glob
              Skips  files  when  there is no other file with the same content whose name matches
              the glob. (Same as --not --includesamecontent)

              For example, if you have inbox and outbox directories, and want to find anything in
              the inbox that has the same content as something in the outbox:

               git annex find inbox --includesamecontent='outbox/*'

       --in=repository
              Matches  only  when git-annex believes that the content is present in a repository.
              Note that it does not check the repository to verify that it still has the content.

              The repository should be specified using the name of a configured  remote,  or  the
              UUID or description of a repository. For the current repository, use --in=here

       --in=repository@{date}
              Matches only when the content was present in a repository on the given date.

              The  date  is specified in the same syntax documented in gitrevisions(7). Note that
              this uses the reflog, so dates far in the past cannot be queried.

              For example, you might need to run git annex drop . to  temporarily  free  up  disk
              space.  The  next day, you can get back the files you dropped using git annex get .
              --in=here@{yesterday}

       --copies=number
              Matches only when git-annex believes there are the specified number of  copies,  or
              more. Note that it does not check remotes to verify that the copies still exist.

       --copies=trustlevel:number
              Matches  only  when git-annex believes there are the specified number of copies, on
              remotes with the specified trust level. For example, --copies=trusted:2

              To match any trust level at or higher than a given level,  use  'trustlevel+'.  For
              example, --copies=semitrusted+:2

       --copies=groupname:number
              Matches  only  when git-annex believes there are the specified number of copies, on
              remotes in the specified group. For example, --copies=archive:2

       --lackingcopies=number
              Matches only when git-annex beleives that the specified number or  more  additional
              copies to be made in order to satisfy numcopies settings.

       --approxlackingcopies=number
              Like  lackingcopies,  but does not look at .gitattributes annex.numcopies settings.
              This makes it significantly faster.

       --inbackend=name
              Matches only when content is stored using the specified key-value backend.

       --securehash
              Matches only when content is hashed using a cryptographically secure function.

       --inallgroup=groupname
              Matches only when git-annex believes content is present in all repositories in  the
              specified group.

       --smallerthan=size

       --largerthan=size
              Matches  only  when  the  content  is is smaller than, or larger than the specified
              size.

              The size can be specified with any commonly used units, for example,  "0.5  gb"  or
              "100 KiloBytes"

       --metadata field=glob
              Matches  only when there is a metadata field attached with a value that matches the
              glob. The values of metadata fields are matched case insensitively.

       --metadata field<value / --metadata field>value

       --metadata field<=value / --metadata field>=value
              Matches only when there is a metadata field attached with a value that is less then
              or greater than the specified value, respectively.

              When  both  values are numbers, the comparison is done numerically.  When one value
              is not a number, the values are instead compared lexicographically.

              (Note that you will need to quote the second parameter to  avoid  the  shell  doing
              redirection.)

       --want-get
              Matches  only  when the preferred content settings for the local repository make it
              want to get content. Note that this will match even when  the  content  is  already
              present, unless limited with e.g., --not --in=here

       --want-drop
              Matches  only  when the preferred content settings for the local repository make it
              want to drop content. Note that this will  match  even  when  the  content  is  not
              present, unless limited with e.g., --not --in=here

              Things  that this matches will not necessarily be dropped by git-annex drop --auto.
              This does not check that there are enough copies to drop. Also the same content may
              be used by a file that is not wanted to be dropped.

       --want-get-by=repository
              Matches  only when the preferred content settings for the specified repository make
              it want to get content. Note that this will match even when the content is  already
              present in that repository, unless limited with e.g., --not --in=repository

              The  repository  should  be specified using the name of a configured remote, or the
              UUID or description of a repository. --want-get-by=here is the same as --want-get.

       --want-drop-by=repository
              Matches only when the preferred content settings for the specificed repository make
              it  want  to  drop  content. Note that this will match even when the content is not
              present, unless limited with e.g., --not --in=repository

              The repository should be specified using the name of a configured  remote,  or  the
              UUID   or   description  of  a  repository.  --want-drop-by=here  is  the  same  as
              --want-drop.

       --accessedwithin=interval
              Matches when the content was accessed recently, within the specified time interval.

              The interval can be in the form "5m" or "1h" or "2d" or "1y", or a combination such
              as "1h5m".

              So  for  example,  --accessedwithin=1d matches when the content was accessed within
              the past day.

              If the OS or filesystem  does  not  support  access  times,  this  will  not  match
              anything.

       --unlocked
              Matches annexed files that are unlocked.

       --locked
              Matches annexed files that are locked.

       --mimetype=glob
              Looks up the MIME type of a file, and checks if the glob matches it.

              For example, --mimetype="text/*" will match many varieties of text files, including
              "text/plain", but also "text/x-shellscript", "text/x-makefile", etc.

              The MIME types are the same that are displayed by running file --mime-type

              If the file's annexed content is not present, the file will not match.

              This is only available to use when git-annex was built  with  the  MagicMime  build
              flag.

       --mimeencoding=glob
              Looks up the MIME encoding of a file, and checks if the glob matches it.

              For example, --mimeencoding=binary will match many kinds of binary files.

              The MIME encodings are the same that are displayed by running file --mime-encoding

              If the file's annexed content is not present, the file will not match.

              This  is  only  available  to use when git-annex was built with the MagicMime build
              flag.

       --anything
              Always matches. One way this can be useful is git-annex find --anything  will  list
              all annexed files, whether their content is present or not.

       --nothing
              Never matches. (Same as --not --anything)

       --not  Inverts  the next matching option. For example, to match when there are less than 3
              copies, use --not --copies=3

       --and  Requires that both the previous and the next matching option matches.  The default.

       --or   Requires that either the previous, or the next matching option matches.

       -(     Opens a group of matching options.

       -)     Closes a group of matching options.

SEE ALSO

       git-annex(1)

AUTHOR

       Joey Hess <id@joeyh.name>

                                                                    git-annex-matching-options(1)