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