Provided by: git-annex_10.20240129-1build1_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 --excludesamecontent)

              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.

              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

              Note that this does not check remote repositories to verify that content is still present on them.
              However, when checking the current repository, it does verify that content is present in it.

       --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}

       --expected-present
              Matches only when git-annex believes that the content is present in the local repository.

              This is like --in=here, except it does not verify that the content is actually present. So it  can
              be used in situations where the location tracking information is known to be out of date.

              For  example,  if  a repository is being restored from a backup that did not include the git-annex
              objects, this could be used to get back all files that were expected to be in  it:  git-annex  get
              --expected-present

       --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 believes that the specified number or more additional copies  need  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.

       --onlyingroup=groupname
              Matches  only when git-annex believes content is present in at least one repository that is in the
              specified group, and is not present in any repositories that are not 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)