summaryrefslogtreecommitdiff
path: root/doc/git-annex-matching-options.mdwn
diff options
context:
space:
mode:
Diffstat (limited to 'doc/git-annex-matching-options.mdwn')
-rw-r--r--doc/git-annex-matching-options.mdwn164
1 files changed, 164 insertions, 0 deletions
diff --git a/doc/git-annex-matching-options.mdwn b/doc/git-annex-matching-options.mdwn
new file mode 100644
index 000000000..34cc05c6a
--- /dev/null
+++ b/doc/git-annex-matching-options.mdwn
@@ -0,0 +1,164 @@
+# NAME
+
+git-annex-matching-options - specifying files to act on
+
+# DESCRIPTION
+
+Many git-annex commands support using these options to specify which
+files they act on.
+
+Arbitrarily complicated expressions can be built using these options.
+For example:
+
+ --exclude '*.mp3' --and --not -( --in=usbdrive --or --in=archive -)
+
+The above example prevents git-annex from working on mp3 files whose
+file contents are present at either of two repositories.
+
+# OPTIONS
+
+* `--exclude=glob`
+
+ Skips files matching the glob pattern. The glob is matched relative to
+ the current directory. For example:
+
+ --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:
+
+ --include='*.mp3' --or --include='*.ogg'
+
+ Note that this will not skip anything when using --all or --unused.
+
+* `--in=repository`
+
+ Matches only files that git-annex believes have their contents 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 files currently in the work tree whose content was present in
+ the 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 files that git-annex believes to have 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 files that git-annex believes have 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 files that git-annex believes have the specified number of
+ copies, on remotes in the specified group. For example,
+ `--copies=archive:2`
+
+* `--lackingcopies=number`
+
+ Matches only files that git-annex believes need the specified number or
+ more additional copies to be made in order to satisfy their numcopies
+ settings.
+
+* `--approxlackingcopies=number`
+
+ Like lackingcopies, but does not look at .gitattributes annex.numcopies
+ settings. This makes it significantly faster.
+
+* `--inbackend=name`
+
+ Matches only files whose content is stored using the specified key-value
+ backend.
+
+* `--inallgroup=groupname`
+
+ Matches only files that git-annex believes are present in all repositories
+ in the specified group.
+
+* `--smallerthan=size`
+* `--largerthan=size`
+
+ Matches only files whose content 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 files that have a metadata field attached with a value that
+ matches the glob. The values of metadata fields are matched case
+ insensitively.
+
+* `--want-get`
+
+ Matches files that the preferred content settings for the repository
+ make it want to get. Note that this will match even files that are
+ already present, unless limited with e.g., `--not --in .`
+
+ Note that this will not match anything when using --all or --unused.
+
+* `--want-drop`
+
+ Matches files that the preferred content settings for the repository
+ make it want to drop. Note that this will match even files that have
+ already been dropped, unless limited with e.g., `--in .`
+
+ Note that this will not match anything when using --all or --unused.
+
+* `--not`
+
+ Inverts the next matching option. For example, to only act on
+ files with 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>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.