mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
git-annex/doc/git-annex-matching-options.mdwn

275 lines
8.2 KiB
Text
Raw Normal View History

splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
# NAME
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
git-annex-matching-options - specifying what to act on
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
# DESCRIPTION
Many git-annex commands support using these options to specify which
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
files they act on. Some of these options can also be used by commands to
specify which keys they act on.
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
Arbitrarily complicated expressions can be built using these options.
For example:
better example
2016-04-01 14:58:21 +00:00
--include='*.mp3' --and -( --in=usbdrive --or --in=archive -)
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
better example
2016-04-01 14:58:21 +00:00
The above example makes git-annex work on only mp3 files that are present
in either of two repositories.
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
# OPTIONS
* `--exclude=glob`
Skips files matching the glob pattern. The glob is matched relative to
the current directory. For example:
New matching options --excludesamecontent and --includesamecontent The normalisation of filenames turns out to be the tricky part here, because the associated files coming out of the keys db may look like "./foo/bar" or "../bar". For the former to match a glob like "foo/*", it needs to be normalised. Note that, on windows, normalise "./foo/bar" = "foo\\bar" which a glob like "foo/*" won't match. So the glob is matched a second time, on the toInternalGitPath, so allowing the user to provide a glob with the slashes in either direction. However, this still won't support some wacky edge cases like the user providing a glob of "foo/bar\\*" Sponsored-by: Dartmouth College's Datalad project
2021-05-25 17:05:42 +00:00
git annex get --exclude='*.mp3' --exclude='subdir/*'
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
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:
New matching options --excludesamecontent and --includesamecontent The normalisation of filenames turns out to be the tricky part here, because the associated files coming out of the keys db may look like "./foo/bar" or "../bar". For the former to match a glob like "foo/*", it needs to be normalised. Note that, on windows, normalise "./foo/bar" = "foo\\bar" which a glob like "foo/*" won't match. So the glob is matched a second time, on the toInternalGitPath, so allowing the user to provide a glob with the slashes in either direction. However, this still won't support some wacky edge cases like the user providing a glob of "foo/bar\\*" Sponsored-by: Dartmouth College's Datalad project
2021-05-25 17:05:42 +00:00
git annex get --include='*.mp3' --or --include='*.ogg'
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
Note that this will not skip anything when using --all or --unused.
New matching options --excludesamecontent and --includesamecontent The normalisation of filenames turns out to be the tricky part here, because the associated files coming out of the keys db may look like "./foo/bar" or "../bar". For the former to match a glob like "foo/*", it needs to be normalised. Note that, on windows, normalise "./foo/bar" = "foo\\bar" which a glob like "foo/*" won't match. So the glob is matched a second time, on the toInternalGitPath, so allowing the user to provide a glob with the slashes in either direction. However, this still won't support some wacky edge cases like the user providing a glob of "foo/bar\\*" Sponsored-by: Dartmouth College's Datalad project
2021-05-25 17:05:42 +00:00
* `--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/*'
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
* `--in=repository`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when git-annex believes that the content is present in a
repository. Note that it does not check the repository to verify
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
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}`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when the content was present in a repository on the given
date.
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
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`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when git-annex believes there are the specified number
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
of copies, or more. Note that it does not check remotes to verify that
the copies still exist.
* `--copies=trustlevel:number`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when git-annex believes there are the specified number of
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
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`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when git-annex believes there are the specified number of
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
copies, on remotes in the specified group. For example,
`--copies=archive:2`
* `--lackingcopies=number`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when git-annex beleives that the specified number or
more additional copies to be made in order to satisfy numcopies
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
settings.
* `--approxlackingcopies=number`
Like lackingcopies, but does not look at .gitattributes annex.numcopies
settings. This makes it significantly faster.
* `--inbackend=name`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when content is stored using the specified key-value
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
backend.
securehash matching Added --securehash option to match files using a secure hash function, and corresponding securehash preferred content expression. This commit was sponsored by Ethan Aubin.
2017-02-27 19:02:38 +00:00
* `--securehash`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when content is hashed using a cryptographically
securehash matching Added --securehash option to match files using a secure hash function, and corresponding securehash preferred content expression. This commit was sponsored by Ethan Aubin.
2017-02-27 19:02:38 +00:00
secure function.
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
* `--inallgroup=groupname`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when git-annex believes content is present in
all repositories in the specified group.
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
* `--smallerthan=size`
* `--largerthan=size`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when the content is is smaller than, or larger than the
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
specified size.
The size can be specified with any commonly used units, for example,
"0.5 gb" or "100 KiloBytes"
* `--metadata field=glob`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when there is a metadata field attached with a value that
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
matches the glob. The values of metadata fields are matched case
insensitively.
Support --metadata field<number, --metadata field>number etc to match ranges of numeric values. Similarly (well, for free), support preferred content expressions like metadata=field<number and metadata=field>number
2016-02-27 14:55:02 +00:00
* `--metadata field<number` / `--metadata field>number`
* `--metadata field<=number` / `--metadata field>=number`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches only when there is a metadata field attached with a value that
Support --metadata field<number, --metadata field>number etc to match ranges of numeric values. Similarly (well, for free), support preferred content expressions like metadata=field<number and metadata=field>number
2016-02-27 14:55:02 +00:00
is a number and is less than or greater than the specified number.
(Note that you will need to quote the second parameter to avoid
the shell doing redirection.)
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
* `--want-get`
new matching options --want-get-by and --want-drop-by Sponsored-by: Graham Spencer on Patreon
2022-07-28 17:26:03 +00:00
Matches only when the preferred content settings for the local repository
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
make it want to get content. Note that this will match even when
new matching options --want-get-by and --want-drop-by Sponsored-by: Graham Spencer on Patreon
2022-07-28 17:26:03 +00:00
the content is already present, unless limited with e.g., `--not --in=here`
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
* `--want-drop`
new matching options --want-get-by and --want-drop-by Sponsored-by: Graham Spencer on Patreon
2022-07-28 17:26:03 +00:00
Matches only when the preferred content settings for the local repository
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
make it want to drop content. Note that this will match even when
new matching options --want-get-by and --want-drop-by Sponsored-by: Graham Spencer on Patreon
2022-07-28 17:26:03 +00:00
the content is not present, unless limited with e.g., `--not --in=here`
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Things that this matches will not necessarily be dropped by
fix longstanding indeterminite preferred content for duplicated file problem * drop: When two files have the same content, and a preferred content expression matches one but not the other, do not drop the file. * sync --content, assistant: Fix an edge case where a file that is not preferred content did not get dropped. The sync --content edge case is that handleDropsFrom loaded associated files and used them without verifying that the information from the database was not stale. It seemed best to avoid changing --want-drop's behavior, this way when debugging a preferred content expression with it, the files matched will still reflect the expression. So added a note to the --want-drop documentation, to make clear it may not behave identically to git-annex drop --auto. While it would be possible to introspect the preferred content expression to see if it matches on filenames, and only look up the associated files when it does, it's generally fairly rare for 2 files to have the same content, and the database lookup is already avoided when there's only 1 file, so I did not implement that further optimisation. Note that there are still some situations where the associated files database does not get locked files recorded in it, which will prevent this fix from working. Sponsored-by: Dartmouth College's Datalad project
2021-05-24 18:02:50 +00:00
`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.
new matching options --want-get-by and --want-drop-by Sponsored-by: Graham Spencer on Patreon
2022-07-28 17:26:03 +00:00
* `--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`.
Added --accessedwithin matching option. Useful for dropping old objects from cache repositories. But also, quite a genrally useful thing to have.. Rather than imitiating find's -atime and other options, all of which are pretty horrible to use, I made this match files accessed within a time period, using the same duration format used by git-annex schedule and --limit-time In passing, changed the --limit-time option parser to parse the duration, instead of having it later throw an error. This commit was supported by the NSF-funded DataLad project.
2018-08-01 19:20:18 +00:00
* `--accessedwithin=interval`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Matches when the content was accessed recently, within the specified time
Added --accessedwithin matching option. Useful for dropping old objects from cache repositories. But also, quite a genrally useful thing to have.. Rather than imitiating find's -atime and other options, all of which are pretty horrible to use, I made this match files accessed within a time period, using the same duration format used by git-annex schedule and --limit-time In passing, changed the --limit-time option parser to parse the duration, instead of having it later throw an error. This commit was supported by the NSF-funded DataLad project.
2018-08-01 19:20:18 +00:00
interval.
The interval can be in the form "5m" or "1h" or "2d" or "1y", or a
combination such as "1h5m".
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
So for example, `--accessedwithin=1d` matches when the content was
Added --accessedwithin matching option. Useful for dropping old objects from cache repositories. But also, quite a genrally useful thing to have.. Rather than imitiating find's -atime and other options, all of which are pretty horrible to use, I made this match files accessed within a time period, using the same duration format used by git-annex schedule and --limit-time In passing, changed the --limit-time option parser to parse the duration, instead of having it later throw an error. This commit was supported by the NSF-funded DataLad project.
2018-08-01 19:20:18 +00:00
accessed within the past day.
If the OS or filesystem does not support access times, this will not
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
match anything.
Added --accessedwithin matching option. Useful for dropping old objects from cache repositories. But also, quite a genrally useful thing to have.. Rather than imitiating find's -atime and other options, all of which are pretty horrible to use, I made this match files accessed within a time period, using the same duration format used by git-annex schedule and --limit-time In passing, changed the --limit-time option parser to parse the duration, instead of having it later throw an error. This commit was supported by the NSF-funded DataLad project.
2018-08-01 19:20:18 +00:00
added --unlocked and --locked
2019-09-19 16:20:35 +00:00
* `--unlocked`
Matches annexed files that are unlocked.
* `--locked`
Matches annexed files that are locked.
Added --mimetype and --mimeencoding file matching options. Already had these for largefiles matching, but I forgot to add them as command-line options.
2019-09-19 15:32:12 +00:00
* `--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.
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
* `--not`
--batch-keys New --batch-keys option added to these commands: get, drop, move, copy, whereis git-annex-matching-options had to be reworded since some of its options can be used to match on keys, not only files. Sponsored-by: Luke Shumaker on Patreon
2021-08-25 18:20:33 +00:00
Inverts the next matching option. For example, to match
when there are less than 3 copies, use `--not --copies=3`
splitting up the man page Common command man pages all split out and often expanded. A few sections split out into their own pages. Still need to do all the other commands..
2015-03-23 19:36:10 +00:00
* `--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>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.
Reference in a new issue Copy permalink